Shipping Service

Download OpenAPI specification:Download

Emporix: documentation@emporix.com URL: https://emporix.com

Define shipping zones & delivery windows.

Key Features:

Create / configure shipping zones
Set up delivery windows, including blackout days
Set up delivery times with multiple delivery slots per day
Calculate shipping costs based on delivery time windows
Find locations from which ideally ship an order or from which a customer can collect and order
Create delivery zones based on postal codes

Key Benefits:

Provide accurate delivery information to customers
Give your customers the choice for their delivery date and time
Better organize your delivery routes
Minimize costs for shipping and delivery, for example by creating zones that are in line with your truck routes

Customer Group Relations

Creating a customer-group relation

Creates a new customer-group relation for the specified site.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.

Request Body schema: application/json

customerId	string Customer's unique identifier.
groupId	string Group's unique identifier.

Responses

201

Resource successfully created.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

post/{tenant}/{site}/cgrelations

Request samples

application/json

{"customerId": "C001",
"groupId": "group1"
}

Response samples

application/json

{"id": "group1",
"link": "https://caas-shipping-dev.scapp.io/saastest2/main/groups/group1"
}

Retrieving customer-group relations

Retrieves a list of customer-group relations for the specified site.

Required scopes

No specific scopes required

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.

Responses

200

Resource successfully retrieved.

401

Unauthorized

500

Some server side error occurred.

get/{tenant}/{site}/cgrelations

Request samples

Response samples

200
401
500

application/json

[{"customerId": "C001",
"groupId": "group1"
},
{"customerId": "C002",
"groupId": "group2"
}
]

Retrieving a customer's customer-group relations

Retrieves customer-group relations for the specified customer.

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
customerId required	string Customer's unique identifier generated when the customer's account is created through the Customer Service.

Responses

200

Resource successfully retrieved.

401

Unauthorized

500

Some server side error occurred.

get/{tenant}/{site}/cgrelations/{customerId}

Request samples

Response samples

200
401
500

application/json

{"customerId": "C001",
"groupId": "group1"
}

Updating a customer's customer-group relations

Updates the customer-group relation for the specified customer.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
customerId required	string Customer's unique identifier generated when the customer's account is created through the Customer Service.

Request Body schema: application/json

customerId	string Customer's unique identifier.
groupId	string Group's unique identifier.

Responses

200

Resource successfully updated.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

put/{tenant}/{site}/cgrelations/{customerId}

Request samples

application/json

{"customerId": "C001",
"groupId": "group1"
}

Response samples

401
403
409
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Deleting a customer's customer-group relation

Deletes the customer-group relation for the specified customer.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
customerId required	string Customer's unique identifier generated when the customer's account is created through the Customer Service.

Responses

204

Resource successfully deleted.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

500

Some server side error occurred.

delete/{tenant}/{site}/cgrelations/{customerId}

Request samples

Response samples

401
403
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Delivery Windows

Retrieving delivery windows by delivery areaDeprecated

Retrieves delivery windows for the specified delivery area and cart.

Note: You can filter out delivery windows before the store's cutoff time using the afterCutOffTime query parameter.

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
deliveryAreaId required	string Delivery area’s unique identifier.
cartId required	string Customer cart’s unique identifier generated when a cart is created through the Cart Service.

query Parameters

siteCode	string Store’s site code. The default site code is `main`.
afterCutOffTime	boolean Default: false If set to `true`, only the delivery windows available after taking the store’s cutoff time into account are retrieved.

Responses

200

Resource successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/areaDeliveryTimes/{deliveryAreaId}/{cartId}

Request samples

Response samples

200
400
401
404
500

application/json

[{"id": "1234567890abcdef123abc0",
"deliveryDate": "2015-06-20T12:00:00.000Z",
"deliveryTimeRange": {"startTime": "15:00",
"endTime": "23:00"
},
"deliveryMethod": "method1",
"cutOffTime": "10:00",
"slotId": "1234567890abcdef123abgi"
},
{"id": "1234567890abcdef123abc1",
"deliveryDate": "2015-06-24T12:00:00.000Z",
"deliveryTimeRange": {"startTime": "12:00",
"endTime": "16:00"
},
"deliveryMethod": "method1",
"cutOffTime": "11:00",
"slotId": "1234567890abcdef123abgh"
}
]

Retrieving delivery windows by cart

Retrieves actual delivery windows for the specified cart.

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
cartId required	string Customer cart’s unique identifier generated when a cart is created through the Cart Service.

query Parameters

postalCode

string

Postal code.

Responses

200

Resource successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/actualDeliveryWindows/{cartId}

Request samples

Response samples

200
400
401
404
500

application/json

[{"id": "1234567890abcdef123abc0",
"deliveryDate": "2015-06-20T12:00:00.000Z",
"deliveryTimeRange": {"startTime": "15:00",
"endTime": "23:00"
},
"deliveryMethod": "method1",
"cutOffTime": "2015-06-20T11:00:00.000Z",
"slotId": "1234567890abcdef123abgh",
"deliveryCycle": "2015-06-20-11"
},
{"id": "1234567890abcdef123abc1",
"deliveryDate": "2015-06-24T12:00:00.000Z",
"deliveryTimeRange": {"startTime": "12:00",
"endTime": "16:00"
},
"deliveryMethod": "method1",
"cutOffTime": "2015-06-20T10:00:00.000Z",
"slotId": "1234567890abcdef123abgi",
"deliveryCycle": "2015-06-24-10"
}
]

Increasing the delivery window counter

Increases the number of orders in the delivery window counter if there is any capacity available.

NOTE

The delivery window counter increases automatically when the Emporix Checkout Service is utilized. This particular endpoint should only be utilized if there is a Custom Checkout Service implementation.

In case of any validation problem, the below errorCodes can be returned:

VALIDATION-DELIVERY-WINDOW-400001: Lack of required slotId property in the request
VALIDATION-DELIVERY-WINDOW-400002: Date is not in correct format
VALIDATION-DELIVERY-WINDOW-400003: Delivery window is fully booked or does not exist for given date
VALIDATION-DELIVERY-WINDOW-400004: Lack of required zoneId property in the request
VALIDATION-DELIVERY-WINDOW-500001: Internal problem with the service

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema:
application/json

deliveryWindowId required	string The selected delivery window
deliveryDate required	string The selected delivery date
slotId	string The slot that was selected for the delivery

Responses

200

OK

400

DeliveryDate is not valid!.

401

Unauthorized

500

Some server side error occurred.

post/{tenant}/actualDeliveryWindows/incrementCounter

Request samples

{"deliveryWindowId": "string",
"deliveryDate": "string",
"slotId": "string"
}

Response samples

200
400
401
500

application/json

true

Validating a delivery window

Validates the specified delivery window.

NOTE

The delivery window is validated automatically when the Emporix Checkout Service is utilized. This particular endpoint should only be utilized if there is a Custom Checkout Service implementation.

In case of any validation problem, the below errorCodes can be returned:

VALIDATION-DELIVERY-WINDOW-400001: Lack of required slotId property in the request
VALIDATION-DELIVERY-WINDOW-400002: Date is not in correct format
VALIDATION-DELIVERY-WINDOW-400003: Delivery window is fully booked or does not exist for given date
VALIDATION-DELIVERY-WINDOW-400004: Lack of required zoneId property in the request
VALIDATION-DELIVERY-WINDOW-500001: Internal problem with the service

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json

deliveryWindowId required	string The selected delivery window
deliveryDate required	string The selected delivery date
slotId	string The slot that was selected for the delivery

Responses

200

Resource successfully validated.

400

DeliveryDate is not valid!.

401

Unauthorized

500

Some server side error occurred.

post/{tenant}/deliveryWindowValidation

Request samples

application/json

{"deliveryWindowId": "25",
"deliveryDate": "2021-01-15T12:00:00.000Z",
"slotId": "slot1"
}

Response samples

200
400
401
500

application/json

true

Shipping Cost

Calculating the final shipping cost

The endpoint will return shipping methods, which contain the matching fee for all zones.

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.

Request Body schema: application/json

customerId	string Customer's unique identifier.
required	object Total amount for the given cart.
	object (Address) Address of billing or delivery that contains customer or company name and location including street, street number, zipcode, and country.
required	object (Address) Address of billing or delivery that contains customer or company name and location including street, street number, zipcode, and country.
	Array of objects (Order item)

Responses

200

Shipping costs calculated.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

404

The requested resource does not exist.

500

Some server side error occurred.

post/{tenant}/{site}/quote

Request samples

application/json

{"customerId": "C001",
"cartTotal": {"amount": 100.34,
"currency": "USD"
},
"shipFromAddress": {"street": "Patterson Fork Road",
"streetNumber": "2095",
"zipCode": "60606",
"city": "Chicago",
"country": "US",
"state": "IL"
},
"shipToAddress": {"street": "Cheng Xiang Zhen Guan Tang Lu",
"streetNumber": "1031",
"extraLine1": "No. 2058",
"extraLine2": "Suzhou City",
"zipCode": "201202",
"city": "Taicang City",
"state": "Jiangsu Province",
"country": "CN"
},
"items": [{"product": {"name": "Effective Java (2nd Edition)",
"sku": "860-1300201986",
"id": "0321356683"
},
"quantity": 2,
"weight": {"value": 820,
"unit": "g"
},
"dimensions": {"length": {"value": 0.185,
"unit": "m"
},
"width": {"value": 0.228,
"unit": "m"
},
"height": {"value": 0.03,
"unit": "m"
}
},
"price": {"amount": 38.88,
"currency": "USD"
},
"requireShipping": true,
"taxable": true
},
{"product": {"name": "Hadoop: The Definitive Guide, Kindle Edition",
"sku": "978-1491901632",
"id": "B00V7B1IZC"
},
"quantity": 1,
"price": {"amount": 22.58,
"currency": "USD"
},
"requireShipping": false,
"taxable": false
}
]
}

Response samples

200
400
401
404
500

application/json

[{"zone": {"id": "europe",
"name": {"en": "Europe",
"de": "Europa"
}
},
"methods": [{"id": "fedex-2dayground",
"name": {"en": "FedEx 2Day",
"de": "FedEx 2 Tage"
},
"fee": {"amount": 4.99,
"currency": "EUR"
}
},
{"id": "dhl",
"name": "DHL",
"fee": {"amount": 2.99,
"currency": "EUR"
}
}
]
},
{"zone": {"id": "northamerica",
"name": {"en": "North America",
"de": "Nord Amerika"
}
},
"methods": [{"id": "dhl-air",
"name": {"en": "DHL Air",
"de": "DHL Flug"
},
"fee": {"amount": 9.99,
"currency": "EUR"
}
},
{"id": "dhl-normal",
"name": "DHL Normal",
"fee": {"amount": 5.99,
"currency": "EUR"
}
}
]
}
]

Calculating the minimum shipping cost

Retrieves the minimum shipping cost.

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.

Request Body schema: application/json

customerId	string Customer's unique identifier.
required	object Total amount for the given cart.
	object (Address) Address of billing or delivery that contains customer or company name and location including street, street number, zipcode, and country.
required	object (Address) Address of billing or delivery that contains customer or company name and location including street, street number, zipcode, and country.
	Array of objects (Order item)

Responses

200

Shipping costs calculated.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

404

The requested resource does not exist.

500

Some server side error occurred.

post/{tenant}/{site}/quote/minimum

Request samples

application/json

{"customerId": "C001",
"cartTotal": {"amount": 100.34,
"currency": "USD"
},
"shipFromAddress": {"street": "Patterson Fork Road",
"streetNumber": "2095",
"zipCode": "60606",
"city": "Chicago",
"country": "US",
"state": "IL"
},
"shipToAddress": {"street": "Cheng Xiang Zhen Guan Tang Lu",
"streetNumber": "1031",
"extraLine1": "No. 2058",
"extraLine2": "Suzhou City",
"zipCode": "201202",
"city": "Taicang City",
"state": "Jiangsu Province",
"country": "CN"
},
"items": [{"product": {"name": "Effective Java (2nd Edition)",
"sku": "860-1300201986",
"id": "0321356683"
},
"quantity": 2,
"weight": {"value": 820,
"unit": "g"
},
"dimensions": {"length": {"value": 0.185,
"unit": "m"
},
"width": {"value": 0.228,
"unit": "m"
},
"height": {"value": 0.03,
"unit": "m"
}
},
"price": {"amount": 38.88,
"currency": "USD"
},
"requireShipping": true,
"taxable": true
},
{"product": {"name": "Hadoop: The Definitive Guide, Kindle Edition",
"sku": "978-1491901632",
"id": "B00V7B1IZC"
},
"quantity": 1,
"price": {"amount": 22.58,
"currency": "USD"
},
"requireShipping": false,
"taxable": false
}
]
}

Response samples

200
400
401
404
500

application/json

{"fee": {"amount": 4.99,
"currency": "EUR"
}
}

Shipping Methods

Creating a shipping method

Creates a new shipping method for the specified site and shipping zone.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language of the payload. When the Content-Language header is empty, all localized fields in a payload should be in a map format, where the key is a language code and the value is a translation.

Example: fr

Request Body schema: application/json

id required	string
required	string or object (LocalizedValue)
	object (Monetary amount) Amount of money in a given currency.
active	boolean Flag indicating whether the shipping method is active.
required	Array of objects (Collection of fees)
shippingTaxCode	string Shipping method's tax code.
shippingGroupId	string Shipping groups unique identifier.

Responses

201

Resource successfully created.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

post/{tenant}/{site}/zones/{zoneId}/methods

Request samples

application/json

{"id": "fedex-2dayground",
"name": "FedEx 2Day",
"active": true,
"maxOrderValue": {"amount": 5000,
"currency": "EUR"
},
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 10,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 9,
"currency": "EUR"
},
"shippingGroupId": "group1"
},
{"minOrderValue": {"amount": 200,
"currency": "EUR"
},
"cost": {"amount": 8,
"currency": "EUR"
},
"shippingGroupId": "group2"
}
]
}

Response samples

application/json

{"id": "fedex-2dayground",
"link": "https://api.emporix.io/caas-shipping/tenant/eu/zones/westerneurope/methods/fedex-2dayground"
}

Retrieving shipping methods

Retrieves shipping methods for the specified site and shipping zone.

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.

query Parameters

active	string If set to `true`, only active methods are returned. If set to `false`, only the inactive methods are returned. If not specified, both active and inactive methods are returned.
expand	string methods: To return zones with expanded shipping methods. fees: To expand the configured fees for those shipping methods. Example: expand=methods,fees

header Parameters

Accept-Language

string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. It can be a priority list working as a fallback mechanism. If the Accept-Language header is empty, all languages for localized fields are returned in a map format where the key is language code and the value is a translation.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7

Responses

200

Resource successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/{site}/zones/{zoneId}/methods

Request samples

Response samples

200
400
401
404
500

application/json

[{"id": "fedex-2dayground",
"name": "FedEx 2Day",
"active": true,
"maxOrderValue": {"amount": 5000,
"currency": "EUR"
},
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 10,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 9,
"currency": "EUR"
},
"shippingGroupId": "group1"
},
{"minOrderValue": {"amount": 200,
"currency": "EUR"
},
"cost": {"amount": 8,
"currency": "EUR"
},
"shippingGroupId": "group2"
}
]
},
{"id": "ups-standard",
"name": "UPS Standard",
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 5,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 2,
"currency": "EUR"
},
"shippingGroupId": "group3"
}
]
}
]

Retrieving a shipping method

Retrieves the specified shipping method's details.

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.
methodId required	string Delivery method's unique identifier.

header Parameters

Accept-Language

string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. It can be a priority list working as a fallback mechanism. If the Accept-Language header is empty, all languages for localized fields are returned in a map format where the key is language code and the value is a translation.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7

Responses

200

Resource successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/{site}/zones/{zoneId}/methods/{methodId}

Request samples

Response samples

200
400
401
404
500

application/json

{"id": "fedex-2dayground",
"name": "FedEx 2Day",
"active": true,
"maxOrderValue": {"amount": 5000,
"currency": "EUR"
},
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 10,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 9,
"currency": "EUR"
},
"shippingGroupId": "group1"
},
{"minOrderValue": {"amount": 200,
"currency": "EUR"
},
"cost": {"amount": 8,
"currency": "EUR"
},
"shippingGroupId": "group2"
}
]
}

Updating a shipping method

Fully updates the specified shipping method.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.
methodId required	string Delivery method's unique identifier.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language of the payload. When the Content-Language header is empty, all localized fields in a payload should be in a map format, where the key is a language code and the value is a translation.

Example: fr

Request Body schema: application/json

id required	string
required	string or object (LocalizedValue)
	object (Monetary amount) Amount of money in a given currency.
active	boolean Flag indicating whether the shipping method is active.
required	Array of objects (Collection of fees)
shippingTaxCode	string Shipping method's tax code.
shippingGroupId	string Shipping groups unique identifier.

Responses

200

Resource successfully updated.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

put/{tenant}/{site}/zones/{zoneId}/methods/{methodId}

Request samples

application/json

{"id": "fedex-2dayground",
"name": "FedEx 2Day",
"active": true,
"maxOrderValue": {"amount": 5000,
"currency": "EUR"
},
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 10,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 9,
"currency": "EUR"
},
"shippingGroupId": "group1"
},
{"minOrderValue": {"amount": 200,
"currency": "EUR"
},
"cost": {"amount": 8,
"currency": "EUR"
},
"shippingGroupId": "group2"
}
]
}

Response samples

400
401
403
404
500

application/json

{"status": 400,
"message": "validation_violation.",
"type": "validation_violation",
"details": [{"field": "name",
"message": "name This field is required. Please provide either value in the content language or a translation map.",
"type": "invalid_field"
},
{"field": "id",
"message": "id must not be null",
"type": "missing_field"
},
{"field": "fees",
"message": "fees may not be empty",
"type": "invalid_field"
}
]
}

Partially updating a shipping method

Partially updates the specified shipping method.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.
methodId required	string Delivery method's unique identifier.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language of the payload. When the Content-Language header is empty, all localized fields in a payload should be in a map format, where the key is a language code and the value is a translation.

Example: fr

Request Body schema: application/json

Partial update operation will update only fields which are in the payload.

id required	string
required	string or object (LocalizedValue)
	object (Monetary amount) Amount of money in a given currency.
active	boolean Flag indicating whether the shipping method is active.
required	Array of objects (Collection of fees)
shippingTaxCode	string Shipping method's tax code.
shippingGroupId	string Shipping groups unique identifier.

Responses

200

Resource successfully updated.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

patch/{tenant}/{site}/zones/{zoneId}/methods/{methodId}

Request samples

application/json

{"id": "fedex-2dayground",
"name": "FedEx 2Day",
"active": true,
"maxOrderValue": {"amount": 5000,
"currency": "EUR"
},
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 10,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 9,
"currency": "EUR"
},
"shippingGroupId": "group1"
},
{"minOrderValue": {"amount": 200,
"currency": "EUR"
},
"cost": {"amount": 8,
"currency": "EUR"
},
"shippingGroupId": "group2"
}
]
}

Response samples

400
401
403
404
500

application/json

{"status": 400,
"message": "validation_violation.",
"type": "validation_violation",
"details": [{"field": "name",
"message": "name This field is required. Please provide either value in the content language or a translation map.",
"type": "invalid_field"
},
{"field": "id",
"message": "id must not be null",
"type": "missing_field"
},
{"field": "fees",
"message": "fees may not be empty",
"type": "invalid_field"
}
]
}

Deleting a shipping method

Deletes the specified shipping method.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.
methodId required	string Delivery method's unique identifier.

Responses

204

Resource successfully deleted.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

delete/{tenant}/{site}/zones/{zoneId}/methods/{methodId}

Request samples

Response samples

401
403
404
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Shipping Zones

Creating a shipping zone

Creates a new shipping zone for the specified site.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language of the payload. When the Content-Language header is empty, all localized fields in a payload should be in a map format, where the key is a language code and the value is a translation.

Example: fr

Request Body schema: application/json

id required	string Delivery zone's unique identifier.
default	boolean Flag indicating whether the zone is the default delivery zone for the site.
required	string or object (LocalizedValue)
required	Array of objects (ShipTo) Collection of shipping destinations
	Array of objects (Collection of shipping methods)

Responses

201

Resource successfully created.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

post/{tenant}/{site}/zones

Request samples

application/json

{"shipTo": [{"country": "DE",
"postalCode": "70190"
}
],
"name": "Zone 1",
"id": "zone1",
"default": true
}

Response samples

application/json

{"id": "zone1",
"link": "https://api.emporix.io/shipping/tenant/site/zones/zone1"
}

Retrieving shipping zones

Retrieves shipping zones for the specified site.

Required scopes

No specific scopes required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.

query Parameters

activeMethods	string If set to `true`, only active methods are included. If set to `false`, only inactive methods are included. If not specified, all expanded shipping methods are included.
expand	string methods: To return zones with expanded shipping methods. fees: To expand the configured fees for those shipping methods. Example: expand=methods,fees

header Parameters

Accept-Language

string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. It can be a priority list working as a fallback mechanism. If the Accept-Language header is empty, all languages for localized fields are returned in a map format where the key is language code and the value is a translation.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7

Responses

200

Resource successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

500

Some server side error occurred.

get/{tenant}/{site}/zones

Request samples

Response samples

200
400
401
500

application/json

[{"id": "zone1",
"name": "Zone 1",
"shipTo": [{"country": "DE",
"postalCode": "70190"
}
],
"default": true
},
{"id": "zone2",
"name": "Zone 2",
"shipTo": [{"country": "DE",
"postalCode": "70192"
}
],
"default": false
}
]

Retrieving a shipping zone

Retrieves the specified shipping zone's details.

Required scopes

No specific scopes required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.

query Parameters

activeMethods	string If set to `true`, only active methods are included. If set to `false`, only inactive methods are included. If not specified, all expanded shipping methods are included.
expand	string methods: To return zones with expanded shipping methods. fees: To expand the configured fees for those shipping methods. Example: expand=methods,fees

header Parameters

Accept-Language

string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. It can be a priority list working as a fallback mechanism. If the Accept-Language header is empty, all languages for localized fields are returned in a map format where the key is language code and the value is a translation.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7

Responses

200

Resource successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/{site}/zones/{zoneId}

Request samples

Response samples

200
400
401
404
500

application/json

{"id": "zone1",
"name": "Zone 1",
"shipTo": [{"country": "DE",
"postalCode": "70190"
}
],
"default": true
}

Updating a shipping zone

Fully updates the specified shipping zone.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language of the payload. When the Content-Language header is empty, all localized fields in a payload should be in a map format, where the key is a language code and the value is a translation.

Example: fr

Request Body schema: application/json

id required	string Delivery zone's unique identifier.
default	boolean Flag indicating whether the zone is the default delivery zone for the site.
required	string or object (LocalizedValue)
required	Array of objects (ShipTo) Collection of shipping destinations
	Array of objects (Collection of shipping methods)

Responses

200

Resource successfully updated.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

put/{tenant}/{site}/zones/{zoneId}

Request samples

application/json

{"shipTo": [{"country": "DE",
"postalCode": "70190"
}
],
"name": "Zone 1",
"id": "zone1",
"default": true
}

Response samples

400
401
403
404
500

application/json

{"status": 400,
"message": "The request violates validation constraints.",
"type": "validation_violation",
"errorCode": "ENTITY-400001",
"details": [{"field": "shipTo[0].country",
"message": "shipTo[0].country Provided value is not a valid country code",
"type": "invalid_field"
}
]
}

Partially updating a shipping zone

Partially updates the specified shipping zone.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language of the payload. When the Content-Language header is empty, all localized fields in a payload should be in a map format, where the key is a language code and the value is a translation.

Example: fr

Request Body schema: application/json

Partial update operation will update only fields which are in the payload.

id required	string Delivery zone's unique identifier.
default	boolean Flag indicating whether the zone is the default delivery zone for the site.
required	string or object (LocalizedValue)
required	Array of objects (ShipTo) Collection of shipping destinations
	Array of objects (Collection of shipping methods)

Responses

200

Resource successfully updated.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

patch/{tenant}/{site}/zones/{zoneId}

Request samples

application/json

{"shipTo": [{"country": "DE",
"postalCode": "70190"
}
],
"name": "Zone 1",
"id": "zone1",
"default": true
}

Response samples

400
401
403
404
500

application/json

{"status": 400,
"message": "The request violates validation constraints.",
"type": "validation_violation",
"errorCode": "ENTITY-400001",
"details": [{"field": "shipTo[0].country",
"message": "shipTo[0].country Provided value is not a valid country code",
"type": "invalid_field"
}
]
}

Deleting a shipping zone

Deletes the specified shipping zone.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
zoneId required	string Shipping zone's unique identifier.

Responses

204

Resource successfully deleted.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

delete/{tenant}/{site}/zones/{zoneId}

Request samples

Response samples

400
401
403
404
500

application/json

{"status": 400,
"message": "There are validation problems, see details section for more information",
"moreInfo": "",
"type": "validation_violation",
"details": [{"field": "tenant",
"message": "size must be between 2 and 16",
"type": "invalid_header"
}
]
}

Shipping Groups

Creating a shipping group

Creates a new shipping group for the specified site.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language of the payload. When the Content-Language header is empty, all localized fields in a payload should be in a map format, where the key is a language code and the value is a translation.

Example: fr

Request Body schema: application/json

id required	string Delivery group's unique identifier.
	string or object (LocalizedValue)

Responses

201

Resource successfully created.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

post/{tenant}/{site}/groups

Request samples

application/json

{"id": "group1",
"description": {"en": "This is the description for the group group1.",
"de": "Dies ist die Beschreibung für die Gruppe group1."
}
}

Response samples

application/json

{"id": "group1",
"link": "https://caas-shipping-dev.scapp.io/saastest2/main/groups/group1"
}

Retrieving shipping groups

Retrieves a list of shipping groups for the specified site.

Required scopes

No specific scopes required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.

header Parameters

Accept-Language

string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. It can be a priority list working as a fallback mechanism. If the Accept-Language header is empty, all languages for localized fields are returned in a map format where the key is language code and the value is a translation.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7

Responses

200

Resource successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

500

Some server side error occurred.

get/{tenant}/{site}/groups

Request samples

Response samples

200
400
401
500

application/json

[{"id": "group1",
"description": {"en": "This is the description for the group group1.",
"de": "Dies ist die Beschreibung für die Gruppe group1."
}
},
{"id": "group2",
"description": {"en": "This is the description for the group group2.",
"de": "Dies ist die Beschreibung für die Gruppe group2."
}
}
]

Retrieving a shipping group

Retrieves the specified shipping group's details.

Required scopes

No specific scopes required.

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
groupId required	string Delivery group's unique identifier.

header Parameters

Accept-Language

string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. It can be a priority list working as a fallback mechanism. If the Accept-Language header is empty, all languages for localized fields are returned in a map format where the key is language code and the value is a translation.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7

Responses

200

Resource successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/{site}/groups/{groupId}

Request samples

Response samples

200
400
401
404
500

application/json

{"id": "group1",
"description": {"en": "This is the description for the group group1.",
"de": "Dies ist die Beschreibung für die Gruppe group1."
}
}

Updating a shipping group

Fully updates the specified shipping group.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
groupId required	string Delivery group's unique identifier.

header Parameters

Content-Language

string

The Content-Language request HTTP header defines language of the payload. When the Content-Language header is empty, all localized fields in a payload should be in a map format, where the key is a language code and the value is a translation.

Example: fr

Request Body schema: application/json

id required	string Delivery group's unique identifier.
	string or object (LocalizedValue)

Responses

200

Resource successfully updated.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

put/{tenant}/{site}/groups/{groupId}

Request samples

application/json

{"id": "group1",
"description": {"en": "This is the description for the group group1.",
"de": "Dies ist die Beschreibung für die Gruppe group1."
}
}

Response samples

400
401
403
404
500

application/json

{"status": 400,
"message": "The request violates validation constraints.",
"type": "validation_violation",
"details": [{"field": "description",
"message": "Cannot specify multiple localizations when 'Content-Language' header is set.",
"type": "invalid_field"
}
]
}

Deleting a shipping group

Deletes the specified shipping group.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.
site required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
groupId required	string Delivery group's unique identifier.

Responses

204

Resource successfully deleted.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

500

Some server side error occurred.

delete/{tenant}/{site}/groups/{groupId}

Request samples

Response samples

401
403
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Sites

Finding sites by postal code

Retrieves a list of sites with zones where the postal code matches the postalCode passed in the request body.

Required scopes

No specific scopes are required.

SecurityoAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters

windowsLimit

number >= 0

The windowsLimit parameter is optional.
The windowsLimit parameter determines the maximum amount of the nearest delivery windows that should be returned for each zone in retrieved sites.
If you do not set the windowsLimit parameter, there will be no delivery window arrays in the response.
If you set the windowsLimit parameter to 0, there will be empty delivery window arrays in the response.

Request Body schema: application/json

postalCode required	string Postal code containing numbers and/or letters.
country	string ISO2 or ISO3 formatted country code.

Responses

200

Resource successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

404

The requested resource does not exist.

500

Some server side error occurred.

post/{tenant}/findSite

Request samples

application/json

{"postalCode": "70190",
"country": "DE"
}

Response samples

200
400
401
404
500

application/json

[{"id": "main",
"zones": [{"id": "deliveryarea",
"name": {"en": "Delivery area Mordor"
},
"shipTo": [{"country": "DE",
"postalCode": "70190"
}
],
"methods": [{"id": "1-2_hours_timeframe",
"name": {"en": "1-2_hours_timeframe",
"de": "1-2 Stunden Lieferzeitfenster"
},
"maxOrderValue": {"amount": 1000,
"currency": "EUR"
},
"active": true,
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 40,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 0,
"currency": "EUR"
},
"shippingGroupId": "group1"
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 12,
"currency": "EUR"
},
"shippingGroupId": "group2"
}
],
"shippingTaxCode": "HALF"
},
{"id": "3_hours_timeframe",
"name": {"en": "3_hours_timeframe",
"de": "3 Stunden Lieferzeitfenster"
},
"maxOrderValue": {"amount": 1000,
"currency": "EUR"
},
"active": true,
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 30,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 30,
"currency": "EUR"
},
"cost": {"amount": 31,
"currency": "EUR"
},
"shippingGroupId": "group1"
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 32,
"currency": "EUR"
},
"shippingGroupId": "group2"
}
],
"shippingTaxCode": "HALF"
},
{"id": "4-more_hours_timeframe",
"name": {"en": "4-more hours timeframe",
"de": "4-mehr Stunden Lieferzeitfenster"
},
"maxOrderValue": {"amount": 2000,
"currency": "EUR"
},
"active": true,
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 20,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 30,
"currency": "EUR"
},
"cost": {"amount": 41,
"currency": "EUR"
},
"shippingGroupId": "group1"
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 42,
"currency": "EUR"
},
"shippingGroupId": "group2"
}
],
"shippingTaxCode": "ZERO"
},
{"id": "pickup",
"name": {"en": "pickup",
"de": "pickup"
},
"maxOrderValue": {"amount": 1000,
"currency": "EUR"
},
"active": true,
"fees": [{"minOrderValue": {"amount": 0,
"currency": "EUR"
},
"cost": {"amount": 18,
"currency": "EUR"
}
},
{"minOrderValue": {"amount": 50,
"currency": "EUR"
},
"cost": {"amount": 55,
"currency": "EUR"
},
"shippingGroupId": "group1"
}
],
"shippingTaxCode": "ZERO"
}
],
"actualDeliveryWindows": [{"id": "5b5572a71cf31a000f31eee6",
"deliveryDate": "2020-12-08T12:00:00.000Z",
"deliveryTimeRange": {"startTime": "15:00",
"endTime": "22:00"
},
"zoneId": "deliveryarea",
"deliveryMethod": "method1",
"cutOffTime": "2020-12-08T11:00:00.000Z",
"slotId": "1234567890abcdef123abgi",
"deliveryCycle": "2020-12-08-11"
},
{"id": "5b5572a71cf31a000f31eee6",
"deliveryDate": "2020-12-15T12:00:00.000Z",
"deliveryTimeRange": {"startTime": "15:00",
"endTime": "22:00"
},
"deliveryCycle": "2020-12-15-10",
"zoneId": "deliveryarea",
"deliveryMethod": "method1",
"cutOffTime": "2020-12-15T10:00:00.000Z",
"slotId": "1234567890abcdef123abgh"
}
]
}
],
"metadata": {"createdAt": "2020-10-19T13:04:09.894Z",
"modifiedAt": "2020-10-19T13:04:10.979Z",
"version": 1
}
}
]

Delivery Times Management

Retrieving all delivery times

Returns all the delivery times defined for the given tenant.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-500001: Internal problem with the service

Required scopes

shipping.shipping_read

SecurityoAuth2

Request

path Parameters

tenant

required

string

Responses

200

OK

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

500

Some server side error occurred.

get/{tenant}/delivery-times

Request samples

Response samples

200
401
403
500

application/json

[{"siteCode": "main",
"name": "deliverytime1",
"isDeliveryDay": true,
"zoneId": "zone1",
"day": {"weekday": "FRIDAY"
},
"isForAllZones": false,
"timeZoneId": "Europe/Warsaw",
"deliveryDayShift": 0,
"slots": [{"shippingMethod": "method1",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"deliveryCycleName": "morning"
},
"capacity": 100
}
],
"metadata": {"createdAt": "2020-10-19T13:04:09.894Z",
"modifiedAt": "2020-10-19T13:04:10.979Z",
"version": 1
}
},
{"siteCode": "main",
"timeZoneId": "UTC",
"name": "deliverytime2",
"isDeliveryDay": true,
"zoneId": "zone2",
"day": {"singleDate": "2023-06-12T10:00:00.000Z"
},
"isForAllZones": false,
"deliveryDayShift": 2,
"slots": [{"shippingMethod": "method1",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"cutOffDayShift": 1,
"deliveryCycleName": "morning"
},
"capacity": 100
}
],
"metadata": {"createdAt": "2020-10-19T13:04:09.894Z",
"modifiedAt": "2020-10-19T13:04:10.979Z",
"version": 1
}
}
]

Creating a delivery time

Creates a single delivery time. Delivery time allows to specify the cut off times for a specific zone and day of the week.

The endpoint has a validation which checks:

if the zoneId belongs to the site
if provided slots id are not duplicated
if the site exists in the system
if the timeFrom is before timeTo

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-400001: Non-delivery day cannot have declared slots property
DELIVERY-TIME-400003: Delivery time of weekday type overlaps on existing one
DELIVERY-TIME-400004: Delivery time of singleDay type overlaps on existing one
DELIVERY-TIME-400005: Slot overlaps delivery time of another slots in given delivery time
DELIVERY-TIME-400006: Delivery time of datePeriod type overlaps on existing one
DELIVERY-TIME-400007: Duplicated time ranges and cutOff time different slots
DELIVERY-TIME-400008: 'ZoneId' cannot be provided when isForAllZones flag is active
DELIVERY-TIME-400009: Provided zone not exist in provided site
DELIVERY-TIME-400010: Provided shipping method does not belong to the given zone
DELIVERY-TIME-400011: Delivery 'timeFrom' cannot be after 'timeTo'
DELIVERY-TIME-400012: Delivery time dateFrom cannot be after dateTo
DELIVERY-TIME-400013: isForAllZones flag cannot be active for delivery day
DELIVERY-TIME-400014: Zone id must be provided for delivery day
DELIVERY-TIME-400015: There are duplicated slot ids in the slots array
DELIVERY-TIME-400016: Provided timeZoneId is incorrect
DELIVERY-TIME-400017: Timezone indicates different time shift than provided delivery time
DELIVERY-TIME-400018: Delivery cutOffTime cannot be after 'timeTo'
DELIVERY-TIME-404001: Provided site does not exist
DELIVERY-TIME-409001: Delivery time with given id already exists in the system
DELIVERY-TIME-500001: Internal problem with the service
DELIVERY-TIME-SLOT-400001: There are overlapping slot id in the request
DELIVERY-TIME-SLOT-400005: The slot cut off day is set when the delivery time date or period is set
DELIVERY-TIME-SLOT-400006: The slot cut off day is set when the delivery day shift is set

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant

required

string

query Parameters

validateOverlap

boolean

Default: true

The flag allows to enable or disable the validation which checks if the delivery time ranges from slots of the same shipping method overlap each other.

Request Body schema: application/json

id	string Delivery Time ID: Autogenerated (if not provided in request) or User-Defined
name	string Optional name for Delivery Time
siteCode required	string Site code for which the Delivery Time is assigned
isDeliveryDay required	boolean `true` indicates that the Delivery Time holds delivery date information, whereas `false` represents that the Delivery Time configuration has disabled delivery for a specific date or time period.
zoneId	string ID of the delivery zone for which the Delivery Time is valid
required	object (Delivery Day) This attribute holds the time configuration for which the Delivery Time is valid. Only a single attribute can be set at any given moment.
	Array of objects (Slot) This attribute holds information about the established timeslots and cut-off times that are set up for a specific Delivery Time
isForAllZones	boolean Flag which indicates if the non-delivery time is defined for the same day, period or weekday for all zones of the site
timeZoneId required	string Id of the time zone for which the Delivery Time should be created (e.g. Europe/Warsaw).
deliveryDayShift	integer >= 0 Default: 0 Indicates in how many days the order has been delivered when the order has been completed before cut-off time.

Responses

201

Created

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

post/{tenant}/delivery-times

Request samples

application/json

{"siteCode": "main",
"name": "deliverytime1",
"isDeliveryDay": true,
"zoneId": "zone1",
"day": {"weekday": "FRIDAY"
},
"isForAllZones": false,
"timeZoneId": "Europe/Warsaw",
"deliveryDayShift": 0,
"slots": [{"shippingMethod": "method1",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"deliveryCycleName": "morning"
},
"capacity": 100
}
]
}

Response samples

application/json

{"id": "647d937ea45a82228e887ab1"
}

Creating multiple delivery times

Creates multiple delivery times in a single request.

The endpoint has a validation which checks:

if the zoneId belongs to the site
if provided slots id are not duplicated
if the site exists in the system
if the timeFrom is before timeTo

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-400001: Non-delivery day cannot have declared slots property
DELIVERY-TIME-400003: Delivery time of weekday type overlaps on existing one
DELIVERY-TIME-400004: Delivery time of singleDay type overlaps on existing one
DELIVERY-TIME-400005: Slot overlaps delivery time of another slots in given delivery time
DELIVERY-TIME-400006: Delivery time of datePeriod type overlaps on existing one
DELIVERY-TIME-400007: Duplicated time ranges and cutOff time different slots
DELIVERY-TIME-400008: 'ZoneId' cannot be provided when isForAllZones flag is active
DELIVERY-TIME-400009: Provided zone not exist in provided site
DELIVERY-TIME-400010: Provided shipping method does not belong to the given zone
DELIVERY-TIME-400011: Delivery 'timeFrom' cannot be after 'timeTo'
DELIVERY-TIME-400012: Delivery time dateFrom cannot be after dateTo
DELIVERY-TIME-400013: isForAllZones flag cannot be active for delivery day
DELIVERY-TIME-400014: Zone id must be provided for delivery day
DELIVERY-TIME-400015: There are duplicated slot ids in the slots array
DELIVERY-TIME-400016: Provided timeZoneId is incorrect
DELIVERY-TIME-400017: Timezone indicates different time shift than provided delivery time
DELIVERY-TIME-400018: Delivery cutOffTime cannot be after 'timeTo'
DELIVERY-TIME-404001: Provided site does not exist
DELIVERY-TIME-409001: Delivery time with given id already exists in the system
DELIVERY-TIME-409002: Optimistic locking - provided metadata.version doesn't match
DELIVERY-TIME-500001: Internal problem with the service
DELIVERY-TIME-SLOT-400001: There are overlapping slot id in the request
DELIVERY-TIME-SLOT-400005: The slot cut off day is set when the delivery time date or period is set
DELIVERY-TIME-SLOT-400006: The slot cut off day is set when the delivery day shift is set

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant

required

string

query Parameters

validateOverlap

boolean

Default: true

The flag allows to enable or disable the validation which checks if the delivery time ranges from slots of the same shipping method overlap each other.

Request Body schema: application/json

Array

id	string Delivery Time ID: Autogenerated (if not provided in request) or User-Defined
name	string Optional name for Delivery Time
siteCode required	string Site code for which the Delivery Time is assigned
isDeliveryDay required	boolean `true` indicates that the Delivery Time holds delivery date information, whereas `false` represents that the Delivery Time configuration has disabled delivery for a specific date or time period.
zoneId	string ID of the delivery zone for which the Delivery Time is valid
required	object (Delivery Day) This attribute holds the time configuration for which the Delivery Time is valid. Only a single attribute can be set at any given moment.
	Array of objects (Slot) This attribute holds information about the established timeslots and cut-off times that are set up for a specific Delivery Time
isForAllZones	boolean Flag which indicates if the non-delivery time is defined for the same day, period or weekday for all zones of the site
timeZoneId required	string Id of the time zone for which the Delivery Time should be created (e.g. Europe/Warsaw).
deliveryDayShift	integer >= 0 Default: 0 Indicates in how many days the order has been delivered when the order has been completed before cut-off time.

Responses

207

Multi-status with all the details

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

500

Some server side error occurred.

post/{tenant}/delivery-times/bulk

Request samples

application/json

[{"siteCode": "main",
"name": "deliverytime1",
"isDeliveryDay": true,
"zoneId": "zone1",
"day": {"weekday": "MONDAY"
},
"isForAllZones": false,
"timeZoneId": "Europe/Warsaw",
"deliveryDayShift": 0,
"slots": [{"shippingMethod": "method1",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"deliveryCycleName": "morning"
},
"capacity": 100
}
]
},
{"siteCode": "main",
"name": "deliverytime1",
"isDeliveryDay": true,
"zoneId": "zone2",
"day": {"weekday": "FRIDAY"
},
"isForAllZones": false,
"timeZoneId": "Europe/Warsaw",
"deliveryDayShift": 0,
"slots": [{"shippingMethod": "method1",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"deliveryCycleName": "morning"
},
"capacity": 100
}
]
}
]

Response samples

207
401
403
500

application/json

[{"id": "123456789",
"index": 0,
"code": 400,
"status": "BAD_REQUEST",
"errorCodes": ["DELIVERY-TIME-404001"
],
"message": "There are validation problems, see details section for more information",
"type": "validation_violation",
"details": ["siteCode cannot be null"
]
}
]

Getting a delivery time

Retrieves a specific delivery time.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-404002: Delivery time with given id does not exist in the system
DELIVERY-TIME-500001: Internal problem with the service

Required scopes

shipping.shipping_read

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string

Responses

200

OK

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/delivery-times/{deliveryTimeId}

Request samples

Response samples

200
401
403
404
500

application/json

{"id": "648700f2d23c990ec006fd06",
"siteCode": "main",
"name": "deliverytime3",
"isDeliveryDay": true,
"zoneId": "zone3",
"day": {"singleDate": "2023-06-12T10:00:00.000Z"
},
"isForAllZones": false,
"timeZoneId": "Europe/Warsaw",
"deliveryDayShift": 0,
"slots": [{"id": "5bb01144-7c72-4659-9ca2-f1f435108c63",
"shippingMethod": "method1",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"cutOffDayShift": 1,
"deliveryCycleName": "morning"
},
"capacity": 100
}
],
"metadata": {"createdAt": "2023-06-12T11:26:42.250Z",
"modifiedAt": "2023-06-12T11:26:42.250Z",
"version": 1
}
}

Updating a delivery time

Updates a single delivery time with a given information. Optimistic locking is validated only if the 'metadata' property is provided.

The endpoint has a validation which checks:

if the zoneId belongs to the site
if provided slots id are not duplicated
if the site exists in the system
if the timeFrom is before timeTo

Note: Depending on a case, a different set of fields is allowed.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-400001: Non-delivery day cannot have declared slots property
DELIVERY-TIME-400002: Provided id from the payload must match id from the url
DELIVERY-TIME-400003: Delivery time of weekday type overlaps on existing one
DELIVERY-TIME-400004: Delivery time of singleDay type overlaps on existing one
DELIVERY-TIME-400005: Slot overlaps delivery time of another slots in given delivery time
DELIVERY-TIME-400006: Delivery time of datePeriod type overlaps on existing one
DELIVERY-TIME-400007: Duplicated time ranges and cutOff time different slots
DELIVERY-TIME-400008: 'ZoneId' cannot be provided when isForAllZones flag is active
DELIVERY-TIME-400009: Provided zone not exist in provided site
DELIVERY-TIME-400010: Provided shipping method does not belong to the given zone
DELIVERY-TIME-400011: Delivery 'timeFrom' cannot be after 'timeTo'
DELIVERY-TIME-400012: Delivery time dateFrom cannot be after dateTo
DELIVERY-TIME-400013: isForAllZones flag cannot be active for delivery day
DELIVERY-TIME-400014: Zone id must be provided for delivery day
DELIVERY-TIME-400015: There are duplicated slot ids in the slots array
DELIVERY-TIME-400016: Provided timeZoneId is incorrect
DELIVERY-TIME-400017: Timezone indicates different time shift than provided delivery time
DELIVERY-TIME-400018: Delivery cutOffTime cannot be after 'timeTo'
DELIVERY-TIME-404001: Provided site does not exist
DELIVERY-TIME-404002: Delivery time with given id does not exist in the system
DELIVERY-TIME-409001: Delivery time with given id already exists in the system
DELIVERY-TIME-409002: Optimistic locking - provided metadata.version does not match
DELIVERY-TIME-500001: Internal problem with the service
DELIVERY-TIME-SLOT-400001: There are overlapping slot id in the request
DELIVERY-TIME-SLOT-400005: The slot cut off day is set when the delivery time date or period is set
DELIVERY-TIME-SLOT-400006: The slot cut off day is set when the delivery day shift is set

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string

query Parameters

validateOverlap

boolean

Default: true

The flag allows to enable or disable the validation which checks if the delivery time ranges from slots of the same shipping method overlap each other.

Request Body schema: application/json

id	string Delivery Time ID: Autogenerated (if not provided in request) or User-Defined
name	string Optional name for Delivery Time
siteCode required	string Site code for which the Delivery Time is assigned
isDeliveryDay required	boolean `true` indicates that the Delivery Time holds delivery date information, whereas `false` represents that the Delivery Time configuration has disabled delivery for a specific date or time period.
zoneId	string ID of the delivery zone for which the Delivery Time is valid
required	object (Delivery Day) This attribute holds the time configuration for which the Delivery Time is valid. Only a single attribute can be set at any given moment.
	Array of objects (Slot) This attribute holds information about the established timeslots and cut-off times that are set up for a specific Delivery Time
isForAllZones	boolean Flag which indicates if the non-delivery time is defined for the same day, period or weekday for all zones of the site
timeZoneId required	string Id of the time zone for which the Delivery Time should be created (e.g. Europe/Warsaw).
deliveryDayShift	integer >= 0 Default: 0 Indicates in how many days the order has been delivered when the order has been completed before cut-off time.
	object metadata of the document

Responses

200

OK

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

put/{tenant}/delivery-times/{deliveryTimeId}

Request samples

application/json

{"siteCode": "main",
"name": "deliverytime1",
"isDeliveryDay": true,
"zoneId": "zone1",
"day": {"weekday": "FRIDAY"
},
"isForAllZones": false,
"timeZoneId": "Europe/Warsaw",
"deliveryDayShift": 0,
"slots": [{"shippingMethod": "method1",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"deliveryCycleName": "morning"
},
"capacity": 100
}
],
"metadata": {"version": 1
}
}

Response samples

application/json

{"status": 400,
"message": "There are validation problems, see details section for more information",
"moreInfo": "",
"type": "validation_violation",
"details": [{"field": "tenant",
"message": "size must be between 2 and 16",
"type": "invalid_header"
}
]
}

Partial updating of a delivery time

Partially updates a single delivery time with a given information.

Note:

Depending on a case, a different set of fields is allowed.

The endpoint has a validation which checks:

if the zoneId belongs to the site
if provided slots id are not duplicated
if the site exists in the system
if the timeFrom is before timeTo

The patch request consists of set of operation, that should be defined according to RFC-6902 standard

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-400001: Non-delivery day cannot have declared slots property
DELIVERY-TIME-400002: Provided id from the payload must match id from the url
DELIVERY-TIME-400003: Delivery time of weekday type overlaps on existing one
DELIVERY-TIME-400004: Delivery time of singleDay type overlaps on existing one
DELIVERY-TIME-400005: Slot overlaps delivery time of another slots in given delivery time
DELIVERY-TIME-400006: Delivery time of datePeriod type overlaps on existing one
DELIVERY-TIME-400007: Duplicated time ranges and cutOff time different slots
DELIVERY-TIME-400008: 'ZoneId' cannot be provided when isForAllZones flag is active
DELIVERY-TIME-400009: Provided zone not exist in provided site
DELIVERY-TIME-400010: Provided shipping method does not belong to the given zone
DELIVERY-TIME-400011: Delivery 'timeFrom' cannot be after 'timeTo'
DELIVERY-TIME-400012: Delivery time dateFrom cannot be after dateTo
DELIVERY-TIME-400013: isForAllZones flag cannot be active for delivery day
DELIVERY-TIME-400014: Zone id must be provided for delivery day
DELIVERY-TIME-400015: There are duplicated slot ids in the slots array
DELIVERY-TIME-400016: Provided timeZoneId is incorrect
DELIVERY-TIME-400017: Timezone indicates different time shift than provided delivery time
DELIVERY-TIME-400018: Delivery cutOffTime cannot be after 'timeTo'
DELIVERY-TIME-404001: Provided site does not exist
DELIVERY-TIME-404002: Delivery time with given id does not exist in the system
DELIVERY-TIME-409001: Delivery time with given id already exists in the system
DELIVERY-TIME-500001: Internal problem with the service
DELIVERY-TIME-SLOT-400001: There are overlapping slot id in the request
DELIVERY-TIME-SLOT-400005: The slot cut off day is set when the delivery time date or period is set
DELIVERY-TIME-SLOT-400006: The slot cut off day is set when the delivery day shift is set

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string

query Parameters

validateOverlap

boolean

Default: true

The flag allows to enable or disable the validation which checks if the delivery time ranges from slots of the same shipping method overlap each other.

Request Body schema: application/json

Array

op	string Indicates an operation which should be done. Available operations: `add`, `remove` and `replace`
path	string Indicates a path for which the value should be applied. For example: `/shippingMethod`, `/cutOffTime/day`
	string or object Indicates a value that should be changed or added. The value can be of a primitive type, like string, number, boolean or it can be an object or an array.

Responses

200

OK

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

patch/{tenant}/delivery-times/{deliveryTimeId}

Request samples

application/json

[{"op": "replace",
"path": "/name",
"value": "newdeliverytime"
}
]

Response samples

400
401
403
404
500

application/json

{"status": 400,
"message": "There are validation problems, see details section for more information",
"moreInfo": "",
"type": "validation_violation",
"details": [{"field": "tenant",
"message": "size must be between 2 and 16",
"type": "invalid_header"
}
]
}

Deleting a delivery time

Deletes a specific delivery time with all slots that it had created.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-404001: Provided site does not exist
DELIVERY-TIME-404002: Delivery time with given id does not exist in the system
DELIVERY-TIME-500001: Internal problem with the service

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string

Responses

204

No Content

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

500

Some server side error occurred.

delete/{tenant}/delivery-times/{deliveryTimeId}

Request samples

Response samples

401
403
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Delivery Times Slots Management

Getting all the delivery time slots

Retrieves all the slots for a given delivery time.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-404002: Delivery time with given id does not exist
DELIVERY-TIME-500001: Internal problem with the service

Required scopes

shipping.shipping_read

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string

Responses

200

OK

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/delivery-times/{deliveryTimeId}/slots

Request samples

Response samples

200
401
403
404
500

application/json

[{"id": "5bb01144-7c72-4659-9ca2-f1f435108c63",
"shippingMethod": "method1",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"cutOffDayShift": 1,
"deliveryCycleName": "morning"
},
"capacity": 100
}
]

Creating a delivery time slot

Creates a new time slot for the given delivery time.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-400003: Delivery time of weekday type overlaps on existing one
DELIVERY-TIME-400004: Delivery time of singleDay type overlaps on existing one
DELIVERY-TIME-400005: Slot overlaps delivery time of another slots in given delivery time
DELIVERY-TIME-400006: Delivery time of datePeriod type overlaps on existing one
DELIVERY-TIME-400007: Duplicated time ranges and cutOff time different slots
DELIVERY-TIME-400010: Provided shipping method does not belong to the given zone
DELIVERY-TIME-400011: Delivery 'timeFrom' cannot be after 'timeTo'
DELIVERY-TIME-400015: There are duplicated slot ids in the slots array
DELIVERY-TIME-400018: Delivery cutOffTime cannot be after 'timeTo'
DELIVERY-TIME-404001: Delivery time with given id does not exist
DELIVERY-TIME-500001: Internal problem with the service
DELIVERY-TIME-SLOT-400001: There are overlapping slot id in the request
DELIVERY-TIME-SLOT-400002: The slot id from the payload must match the id from the url
DELIVERY-TIME-SLOT-400003: Slot with provided id already exists in the given delivery time
DELIVERY-TIME-SLOT-400004: Duplicated time ranges and cutOff time in the existing slots
DELIVERY-TIME-SLOT-400005: The slot cut off day is set when the delivery time date or period is set
DELIVERY-TIME-SLOT-400006: The slot cut off day is set when the delivery day shift is set

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string

query Parameters

validateOverlap

boolean

Default: true

The flag allows to enable or disable the validation which checks if the delivery time ranges from slots of the same shipping method overlap each other.

Request Body schema: application/json

id	string Delivery Time Slot ID: Autogenerated (if not provided in request) or User-Defined
shippingMethod required	string Selected shipping method which is available for the Delivery Time in the given Time Slot
required	object (Time range) A `from` to `to` time range for which the object is valid
required	object (Cut-Off Time) This denotes the latest point in time by which an action (such as an order or request) must be completed for a specific Delivery Time. This attribute is key in determining the end of a time window for certain operations and helps maintain efficiency in the delivery process.
capacity required	integer A capacity determines how many orders the given Delivery Time Slot can handle

Responses

201

Created

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

post/{tenant}/delivery-times/{deliveryTimeId}/slots

Request samples

application/json

{"shippingMethod": "method2",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"cutOffDayShift": 1,
"deliveryCycleName": "evening"
},
"capacity": 100
}

Response samples

application/json

{"id": "800c4f51-035d-43b4-bbbb-b9ba0c630242"
}

Deleting all the delivery time slots

Deletes all the time slots for the given delivery time.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-404002: Delivery time with given id does not exist
DELIVERY-TIME-500001: Internal problem with the service

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string

Responses

204

No Content

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

delete/{tenant}/delivery-times/{deliveryTimeId}/slots

Request samples

Response samples

401
403
404
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Getting a delivery time slot

Retrieves the given delivery time slot's details.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-500001: Internal problem with the service
DELIVERY-TIME-404002: Delivery time with given id doesn't exists in the system
DELIVERY-TIME-SLOT-404001: Slot with provided id doesn't exists in the given delivery time

Required scopes

shipping.shipping_read

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string
slotId required	string

Responses

200

OK

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/delivery-times/{deliveryTimeId}/slots/{slotId}

Request samples

Response samples

200
401
403
404
500

application/json

{"id": "800c4f51-035d-43b4-bbbb-b9ba0c630242",
"shippingMethod": "method2",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"cutOffDayShift": 1,
"deliveryCycleName": "evening"
},
"capacity": 100
}

Updating a delivery time slot

Updates a single delivery time slot with given information.

Note:

Depending on a case, a different set of fields is allowed.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-400003: Delivery time of weekday type overlaps on existing one
DELIVERY-TIME-400004: Delivery time of singleDay type overlaps on existing one
DELIVERY-TIME-400005: Slot overlaps delivery time of another slots in given delivery time
DELIVERY-TIME-400006: Delivery time of datePeriod type overlaps on existing one
DELIVERY-TIME-400007: Duplicated time ranges and cutOff time different slots
DELIVERY-TIME-400010: Provided shipping method does not belong to the given zone
DELIVERY-TIME-400011: Delivery 'timeFrom' cannot be after 'timeTo'
DELIVERY-TIME-400015: There are duplicated slot ids in the slots array
DELIVERY-TIME-400018: Delivery cutOffTime cannot be after 'timeTo'
DELIVERY-TIME-404002: Delivery time with given id does not exist
DELIVERY-TIME-500001: Internal problem with the service
DELIVERY-TIME-SLOT-400001: There are overlapping slot id in the request
DELIVERY-TIME-SLOT-400002: The slot id from the payload must match the id from the url
DELIVERY-TIME-SLOT-400003: Slot with provided id already exists in the given delivery time
DELIVERY-TIME-SLOT-400004: Duplicated time ranges and cutOff time in the existing slots
DELIVERY-TIME-SLOT-404001: Slot with provided id doesn't exists in the given delivery time
DELIVERY-TIME-SLOT-400005: The slot cut off day is set when the delivery time date or period is set
DELIVERY-TIME-SLOT-400006: The slot cut off day is set when the delivery day shift is set

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string
slotId required	string

query Parameters

validateOverlap

boolean

Default: true

The flag allows to enable or disable the validation which checks if the delivery time ranges from slots of the same shipping method overlap each other.

Request Body schema: application/json

id	string Delivery Time Slot ID: Autogenerated (if not provided in request) or User-Defined
shippingMethod required	string Selected shipping method which is available for the Delivery Time in the given Time Slot
required	object (Time range) A `from` to `to` time range for which the object is valid
required	object (Cut-Off Time) This denotes the latest point in time by which an action (such as an order or request) must be completed for a specific Delivery Time. This attribute is key in determining the end of a time window for certain operations and helps maintain efficiency in the delivery process.
capacity required	integer A capacity determines how many orders the given Delivery Time Slot can handle

Responses

200

OK

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

put/{tenant}/delivery-times/{deliveryTimeId}/slots/{slotId}

Request samples

application/json

{"shippingMethod": "method2",
"deliveryTimeRange": {"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {"time": "2023-06-12T06:00:00.000Z",
"cutOffDayShift": 1,
"deliveryCycleName": "evening"
},
"capacity": 100
}

Response samples

application/json

{"status": 400,
"message": "There are validation problems, see details section for more information",
"moreInfo": "",
"type": "validation_violation",
"details": [{"field": "tenant",
"message": "size must be between 2 and 16",
"type": "invalid_header"
}
]
}

Partial updating of a delivery time slot

Partially updates a single delivery time slot with given information.
Note: Depending on a case, a different set of fields is allowed.

The patch request consists of a set of operations, that should be defined according to RFC-6902 standard

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-400003: Delivery time of weekday type overlaps on existing one
DELIVERY-TIME-400004: Delivery time of singleDay type overlaps on existing one
DELIVERY-TIME-400005: Slot overlaps delivery time of another slots in given delivery time
DELIVERY-TIME-400006: Delivery time of datePeriod type overlaps on existing one
DELIVERY-TIME-400007: Duplicated time ranges and cutOff time different slots
DELIVERY-TIME-400010: Provided shipping method does not belong to the given zone
DELIVERY-TIME-400011: Delivery 'timeFrom' cannot be after 'timeTo'
DELIVERY-TIME-400015: There are duplicated slot ids in the slots array
DELIVERY-TIME-400018: Delivery cutOffTime cannot be after 'timeTo'
DELIVERY-TIME-404002: Delivery time with given id does not exist
DELIVERY-TIME-500001: Internal problem with the service
DELIVERY-TIME-SLOT-400001: There are overlapping slot id in the request
DELIVERY-TIME-SLOT-400002: The slot id from the payload must match the id from the url
DELIVERY-TIME-SLOT-400003: Slot with provided id already exists in the given delivery time
DELIVERY-TIME-SLOT-400004: Duplicated time ranges and cutOff time in the existing slots
DELIVERY-TIME-SLOT-404001: Slot with provided id doesn't exists in the given delivery time
DELIVERY-TIME-SLOT-400005: The slot cut off day is set when the delivery time date or period is set
DELIVERY-TIME-SLOT-400006: The slot cut off day is set when the delivery day shift is set

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string
slotId required	string

query Parameters

validateOverlap

boolean

Default: true

The flag allows to enable or disable the validation which checks if the delivery time ranges from slots of the same shipping method overlap each other.

Request Body schema: application/json

Array

op	string Indicates an operation which should be done. Available operations: `add`, `remove` and `replace`
path	string Indicates a path for which the value should be applied. For example: `/shippingMethod`, `/cutOffTime/day`
	string or object Indicates a value that should be changed or added. The value can be of a primitive type, like string, number, boolean or it can be an object or an array.

Responses

200

OK

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

patch/{tenant}/delivery-times/{deliveryTimeId}/slots/{slotId}

Request samples

application/json

[{"op": "replace",
"path": "/shippingMethod",
"value": "testMethod"
}
]

Response samples

400
401
403
404
500

application/json

{"status": 400,
"message": "There are validation problems, see details section for more information",
"moreInfo": "",
"type": "validation_violation",
"details": [{"field": "tenant",
"message": "size must be between 2 and 16",
"type": "invalid_header"
}
]
}

Deleting a delivery time slot

Deletes a single delivery time slot.

In case of any validation problem, the below errorCodes can be returned:

DELIVERY-TIME-404002: Delivery time with given id does not exist
DELIVERY-TIME-500001: Internal problem with the service
DELIVERY-TIME-SLOT-404001: Slot with provided id doesn't exists in the given delivery time

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant required	string
deliveryTimeId required	string
slotId required	string

Responses

204

No Content

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

delete/{tenant}/delivery-times/{deliveryTimeId}/slots/{slotId}

Request samples

Response samples

401
403
404
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Delivery Cycles

Generating a delivery cycle

Generates a delivery cycle.

Required scopes

shipping.shipping_manage

SecurityoAuth2

Request

path Parameters

tenant

required

string

Request Body schema: application/json

deliveryTimeId required	string Id of the delivery time.
slotId required	string Id of the slot.
deliveryDate required	string The selected delivery date

Responses

201

CREATED

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match required scopes.

404

The requested resource does not exist.

500

Some server side error occurred.

post/{tenant}/delivery-cycles/generate

Request samples

application/json

{"deliveryTimeId": "64a80cf4c123c90e6c263789",
"slotId": "bdf61ee4-25f4-48af-94c3-ccea8612aefa",
"deliveryDate": "2020-12-08T12:00:00.000Z"
}

Response samples

201
401
403
404
500

application/json

"string"

Shipping Service

Customer Group Relations

Creating a customer-group relation

Required scopes

path Parameters

Request Body schema: application/json

Retrieving customer-group relations

Required scopes

path Parameters

Retrieving a customer's customer-group relations

Required scopes

path Parameters

Updating a customer's customer-group relations

Required scopes

path Parameters

Request Body schema: application/json

Deleting a customer's customer-group relation

Required scopes

path Parameters

Delivery Windows

Retrieving delivery windows by delivery areaDeprecated

Required scopes

path Parameters

query Parameters

Retrieving delivery windows by cart

Required scopes

path Parameters

query Parameters

Increasing the delivery window counter

NOTE

Required scopes

path Parameters

Request Body schema: application/jsonapplication/xmlapplication/json

Validating a delivery window

NOTE

Required scopes

path Parameters

Request Body schema: application/json

Shipping Cost

Calculating the final shipping cost

Required scopes

path Parameters

Request Body schema: application/json

Calculating the minimum shipping cost

Required scopes

path Parameters

Request Body schema: application/json

Shipping Methods

Creating a shipping method

Required scopes

path Parameters

header Parameters

Request Body schema: application/json

Retrieving shipping methods

Required scopes

path Parameters

query Parameters

header Parameters

Retrieving a shipping method

Required scopes

path Parameters

header Parameters

Updating a shipping method

Required scopes

path Parameters

header Parameters

Request Body schema: application/json

Partially updating a shipping method

Required scopes

path Parameters

header Parameters

Request Body schema: application/json

Deleting a shipping method

Required scopes

path Parameters

Shipping Zones

Creating a shipping zone

Required scopes

path Parameters

header Parameters

Request Body schema:
application/json