Shipping Service

Download OpenAPI specification:Download

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

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
application/json
[
  • {
    },
  • {
    }
]

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
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
application/json
{
  • "fault": {
    }
}

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
application/json
{
  • "fault": {
    }
}

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
application/json
[
  • {
    },
  • {
    }
]

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
application/json
[
  • {
    },
  • {
    }
]

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:
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
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
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": {
    },
  • "shipFromAddress": {
    },
  • "shipToAddress": {
    },
  • "items": [
    ]
}
Response samples
application/json
[
  • {
    },
  • {
    }
]

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": {
    },
  • "shipFromAddress": {
    },
  • "shipToAddress": {
    },
  • "items": [
    ]
}
Response samples
application/json
{
  • "fee": {
    }
}

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": {
    },
  • "fees": [
    ]
}
Response samples
application/json

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
application/json
[
  • {
    },
  • {
    }
]

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
application/json
{
  • "id": "fedex-2dayground",
  • "name": "FedEx 2Day",
  • "active": true,
  • "maxOrderValue": {
    },
  • "fees": [
    ]
}

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": {
    },
  • "fees": [
    ]
}
Response samples
application/json
{
  • "status": 400,
  • "message": "validation_violation.",
  • "type": "validation_violation",
  • "details": [
    ]
}

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": {
    },
  • "fees": [
    ]
}
Response samples
application/json
{
  • "status": 400,
  • "message": "validation_violation.",
  • "type": "validation_violation",
  • "details": [
    ]
}

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
application/json
{
  • "fault": {
    }
}

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": [
    ],
  • "name": "Zone 1",
  • "id": "zone1",
  • "default": true
}
Response samples
application/json

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
application/json
[
  • {
    },
  • {
    }
]

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
application/json
{
  • "id": "zone1",
  • "name": "Zone 1",
  • "shipTo": [
    ],
  • "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": [
    ],
  • "name": "Zone 1",
  • "id": "zone1",
  • "default": true
}
Response samples
application/json
{
  • "status": 400,
  • "message": "The request violates validation constraints.",
  • "type": "validation_violation",
  • "errorCode": "ENTITY-400001",
  • "details": [
    ]
}

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": [
    ],
  • "name": "Zone 1",
  • "id": "zone1",
  • "default": true
}
Response samples
application/json
{
  • "status": 400,
  • "message": "The request violates validation constraints.",
  • "type": "validation_violation",
  • "errorCode": "ENTITY-400001",
  • "details": [
    ]
}

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
application/json
{
  • "status": 400,
  • "message": "There are validation problems, see details section for more information",
  • "moreInfo": "",
  • "type": "validation_violation",
  • "details": [
    ]
}

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": {
    }
}
Response samples
application/json

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
application/json
[
  • {
    },
  • {
    }
]

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
application/json
{
  • "id": "group1",
  • "description": {
    }
}

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": {
    }
}
Response samples
application/json
{
  • "status": 400,
  • "message": "The request violates validation constraints.",
  • "type": "validation_violation",
  • "details": [
    ]
}

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
application/json
{
  • "fault": {
    }
}

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
application/json
[
  • {