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"
}

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.

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"
}
}

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.

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"
}
}

Response samples

200
400
401
404
500

application/json

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

Calculating the shipping cost for a given slot

Retrieves the minimum slot 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.
	object (Address) Address of billing or delivery that contains customer or company name and location including street, street number, zipcode, and country.
slotId required	string The `slotId` for which the quote should be calculated
deliveryWindowId required	string The delivery window id for which the slot with selected shipping method exists

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/slot

Request samples

application/json

{"customerId": "C0012",
"cartTotal": {"amount": 100.34,
"currency": "USD"
},
"deliveryWindowId": "123",
"slotId": "456"
}

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"
}

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"
}

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"
}

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

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

Calculating the shipping cost for a given slot

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

Request Body schema:
application/json