Site settings

Retrieving sites

get

Retrieves a list of site configurations.

---

Required scopes

• site.site_manage

  Note: The site.site_manage scope is only required if you want to retrieve inactive sites.

Authorizations

Path parameters

tenantstringRequired

Your Emporix tenant's name.

Note: The tenant name should always be provided in lowercase.

Query parameters

totalCountbooleanOptional

If set to true, a total number of sites is returned in a response header.

Default: false

includeInactivebooleanOptional

Option	Description
true	Retrieves both the active and inactive sites.
false	Retrieves only the active sites.

Default: false

sortstringOptional

List of properties used to sort the results, separated by colons.

Possible values:

• {fieldName}
• {fieldName}:asc
• {fieldName}:desc

Note: If you want to sort the results by localized properties, the possible values are:

• {fieldName}.{language}
• {fieldName}.{language}:asc
• {fieldName}.{language}:desc

By default, the fields are sorted in ascending order.

pageNumberinteger · min: 1Optional

Page number to be retrieved. The number of the first page is 1.

Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.

Default: 1

pageSizeinteger · min: 1Optional

Number of products to be retrieved per page.

Default: 16

qstringOptional

A standard query parameter used to search for specific values.

Example: name:{productName}

expandstringOptional

Used to expand the following site settings:

• payment
• shipping
• tax
• mixin

Each of the settings (except mixin) can be set to one of the following values:

• all
• active
• none

For retrieving mixin, use the following value:

• *

Example: payment:all,shipping:active,tax:none,mixin:*

Responses

200

OK

application/json

400Error

application/json

401Error

application/json

403Error

application/json

get

HTTPcURLJavaScriptPython

GET /site/{tenant}/sites HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "code": "main",
    "name": "United States",
    "active": true,
    "defaultLanguage": "en",
    "languages": [
      "ar",
      "en",
      "fr",
      "de"
    ],
    "currency": "USD",
    "availableCurrencies": [
      "EUR",
      "GBP",
      "USD",
      "THB",
      "RUB",
      "SAR"
    ],
    "homeBase": {
      "address": {
        "street": "Broadway",
        "streetNumber": "1500",
        "zipCode": "10036",
        "city": "New York",
        "country": "US",
        "state": "NY"
      },
      "location": {
        "latitude": 40.7568658044745,
        "longitude": -73.9858713458565
      }
    },
    "shipToCountries": [
      "US"
    ],
    "assistedBuying": {
      "storefrontUrl": ""
    },
    "metadata": {
      "mixins": {
        "productSettings": "https://res.cloudinary.com/saas-ag/raw/upload/hybris_schema/productSettingsSiteMixIn.v1",
        "generalShopSettings": "https://res.cloudinary.com/saas-ag/raw/upload/hybris_schema/generalShopSettingsSiteMixIn.v10",
        "customerSettings": "https://res.cloudinary.com/saas-ag/raw/upload/hybris_schema/customerSettingsSiteMixIn.v3",
        "orderProcessSettings": "https://res.cloudinary.com/saas-ag/raw/upload/hybris_schema/orderProcessSettingsSiteMixIn.v7",
        "couponSettings": "https://res.cloudinary.com/saas-ag/raw/upload/hybris_schema/couponSettingsSiteMixIn.v4",
        "feeService": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/CAAS/siteFeeService.json",
        "imageSize": "https://res.cloudinary.com/saas-ag/raw/upload/hybris_schema/imageSize.v6",
        "merchantInfo": "https://res.cloudinary.com/saas-ag/raw/upload/hybris_schema/merchantAddressMixin.v10"
      },
      "version": 14
    },
    "default": true
  }
]

Creating a site

post

Creates a new site configuration.

---

Required scopes

• site.site_manage

Authorizations

Path parameters

tenantstringRequired

Your Emporix tenant's name.

Note: The tenant name should always be provided in lowercase.

Body

Information about the site.

codestringOptional

Site's unique identifier.

namestringOptional

Site name.

activebooleanOptional

Flag indicating whether the site is active.

defaultbooleanOptional

Flag indicating whether the site is the tenant's default site.

includesTaxbooleanOptional

Indicates whether prices for the site should be returned in gross (when includesTax=true) or net (when includesTax=false).

defaultLanguagestring · min: 2 · max: 2Optional

Site's default language, compliant with the ISO 639-1 standard.

Pattern: ^[a-z]{2}

languagesstring[]Optional

Languages supported by the site.

Note: The languages must be compliant with the ISO 639-1 standard.

currencystring · min: 3 · max: 3Optional

Currency used by the site, compliant with the ISO 4217 standard.

Pattern: ^[A-Z]{3}

availableCurrenciesstring[]Optional

List of the currencies supported by the site

shipToCountriesstring[]Optional

Codes of countries to which the site ships products.

Note: The country codes must be compliant with the ISO 3166-1 alpha-2 standard.

taxDeterminationBasedOnstring · enumOptional

Specifies whether tax calculation is based on customer billing address or shipping address. Default value is BILLING_ADDRESS.

Possible values:

cartCalculationScaleintegerOptional

Number of decimal points used in the cart calculation. Must be zero or a positive value.

Default: 2

Responses

201

Created

application/json

400Error

application/json

401Error

application/json

403Error

application/json

post

HTTPcURLJavaScriptPython

POST /site/{tenant}/sites HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 244

{
  "code": "test2",
  "name": "postmanTestSiteName",
  "active": false,
  "default": false,
  "defaultLanguage": "en",
  "languages": [
    "en"
  ],
  "currency": "GBP",
  "homeBase": {
    "address": {
      "country": "GB",
      "zipCode": "12345"
    }
  },
  "shipToCountries": [
    "GB"
  ],
  "mixins": {},
  "metadata": {}
}

{
  "Response example": {
    "value": {
      "id": "test"
    }
  }
}

Retrieving a site

get

Retrieves a specified site's configuration.

---

Required scopes

• site.site_manage

  Note: The site.site_manage scope is only required if you want to retrieve an inactive site.

Authorizations

Path parameters

tenantstringRequired

Your Emporix tenant's name.

Note: The tenant name should always be provided in lowercase.

siteCodestringRequired

Site code, defined when a site is created.

Query parameters

expandstringOptional

Used to expand the following site settings:

• payment
• shipping
• tax
• mixin

Each of the settings (except mixin) can be set to one of the following values:

• all
• active
• none

For retrieving mixin, use the following value:

• *

Example: payment:all,shipping:active,tax:none,mixin:*

Responses

200

Example response

application/json

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /site/{tenant}/sites/{siteCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "code": "test2",
  "name": "postmanTestSiteName",
  "active": false,
  "defaultLanguage": "en",
  "languages": [
    "en"
  ],
  "currency": "GBP",
  "homeBase": {
    "address": {
      "zipCode": "12345",
      "country": "GB"
    }
  },
  "shipToCountries": [
    "GB"
  ],
  "metadata": {
    "mixins": {},
    "version": 0
  },
  "default": true
}

Fully updating a site

put

Fully updates a specified site's configuration.

You can also use this endpoint to update the configuration of the following services:

• payment

• shipping

• tax

Note: To update an inactive service configuration, you need to use the expand query parameter.

---

Required scopes

• site.site_manage

Authorizations

Path parameters

tenantstringRequired

Your Emporix tenant's name.

Note: The tenant name should always be provided in lowercase.

siteCodestringRequired

Site code, defined when a site is created.

Query parameters

expandstringOptional

Used to expand the following site settings:

• payment
• shipping
• tax
• mixin

Each of the settings (except mixin) can be set to one of the following values:

• all
• active
• none

For retrieving mixin, use the following value:

• *

Example: payment:all,shipping:active,tax:none,mixin:*

Body

Information about the site.

codestringOptional

Site's unique identifier.

namestringOptional

Site name.

activebooleanOptional

Flag indicating whether the site is active.

defaultbooleanOptional

Flag indicating whether the site is the tenant's default site.

includesTaxbooleanOptional

Indicates whether prices for the site should be returned in gross (when includesTax=true) or net (when includesTax=false).

defaultLanguagestring · min: 2 · max: 2Optional

Site's default language, compliant with the ISO 639-1 standard.

Pattern: ^[a-z]{2}

languagesstring[]Optional

Languages supported by the site.

Note: The languages must be compliant with the ISO 639-1 standard.

currencystring · min: 3 · max: 3Optional

Currency used by the site, compliant with the ISO 4217 standard.

Pattern: ^[A-Z]{3}

availableCurrenciesstring[]Optional

List of the currencies supported by the site

shipToCountriesstring[]Optional

Codes of countries to which the site ships products.

Note: The country codes must be compliant with the ISO 3166-1 alpha-2 standard.

taxDeterminationBasedOnstring · enumOptional

Specifies whether tax calculation is based on customer billing address or shipping address. Default value is BILLING_ADDRESS.

Possible values:

cartCalculationScaleintegerOptional

Number of decimal points used in the cart calculation. Must be zero or a positive value.

Default: 2

Responses

200

The request was successful. The services configuration has been updated.

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

409

Conflict

500

Internal Server Error

put

HTTPcURLJavaScriptPython

PUT /site/{tenant}/sites/{siteCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 218

{
  "name": "test",
  "active": true,
  "default": false,
  "defaultLanguage": "de",
  "languages": [
    "en",
    "de"
  ],
  "currency": "EUR",
  "homeBase": {
    "address": {
      "country": "GB",
      "zipCode": "12345"
    }
  },
  "shipToCountries": [
    "GB"
  ],
  "mixins": {},
  "metadata": {}
}

No content

Deleting a site

delete

Deletes a specified site.

Important: You cannot delete a site whose default property is set to true.

---

Required scopes

• site.site_manage

Authorizations

Path parameters

tenantstringRequired

Your Emporix tenant's name.

Note: The tenant name should always be provided in lowercase.

siteCodestringRequired

Site code, defined when a site is created.

Responses

204

The request was successful. The site has been deleted.

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

500

Internal Server Error

delete

HTTPcURLJavaScriptPython

DELETE /site/{tenant}/sites/{siteCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Partially updating a site

patch

Partially updates a specified site's configuration.

Required scopes

• site.site_manage

Authorizations

Path parameters

tenantstringRequired

Your Emporix tenant's name.

Note: The tenant name should always be provided in lowercase.

siteCodestringRequired

Site code, defined when a site is created.

Body

Information about the site.

codestringOptional

Site's unique identifier.

namestringOptional

Site name.

activebooleanOptional

Flag indicating whether the site is active.

defaultbooleanOptional

Flag indicating whether the site is the tenant's default site.

includesTaxbooleanOptional

Indicates whether prices for the site should be returned in gross (when includesTax=true) or net (when includesTax=false).

defaultLanguagestring · min: 2 · max: 2Optional

Site's default language, compliant with the ISO 639-1 standard.

Pattern: ^[a-z]{2}

languagesstring[]Optional

Languages supported by the site.

Note: The languages must be compliant with the ISO 639-1 standard.

currencystring · min: 3 · max: 3Optional

Currency used by the site, compliant with the ISO 4217 standard.

Pattern: ^[A-Z]{3}

availableCurrenciesstring[]Optional

List of the currencies supported by the site

shipToCountriesstring[]Optional

Codes of countries to which the site ships products.

Note: The country codes must be compliant with the ISO 3166-1 alpha-2 standard.

taxDeterminationBasedOnstring · enumOptional

Specifies whether tax calculation is based on customer billing address or shipping address. Default value is BILLING_ADDRESS.

Possible values:

cartCalculationScaleintegerOptional

Number of decimal points used in the cart calculation. Must be zero or a positive value.

Default: 2

Responses

200

The request was successful. The site has been updated.

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

409

Conflict

500

Internal Server Error

patch

HTTPcURLJavaScriptPython

PATCH /site/{tenant}/sites/{siteCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "defaultLanguage": "en"
}

No content

Retrieving site codes

get

Retrieves a list of site codes.

---

Required scopes

• site.site_read

• site.site_manage

  Note: The site.site_manage scope is only required if you want to retrieve inactive sites.

Authorizations

Path parameters

tenantstringRequired

Your Emporix tenant's name.

Note: The tenant name should always be provided in lowercase.

Query parameters

includeInactivebooleanOptional

Option	Description
true	Retrieves both the active and inactive sites.
false	Retrieves only the active sites.

Default: false

pageNumberinteger · min: 1Optional

Page number to be retrieved. The number of the first page is 1.

Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.

Default: 1

pageSizeinteger · min: 1Optional

Number of products to be retrieved per page.

Default: 16

sortstringOptional

List of properties used to sort the results, separated by colons.

Possible values:

• {fieldName}
• {fieldName}:asc
• {fieldName}:desc

Note: If you want to sort the results by localized properties, the possible values are:

• {fieldName}.{language}
• {fieldName}.{language}:asc
• {fieldName}.{language}:desc

By default, the fields are sorted in ascending order.

qstringOptional

A standard query parameter used to search for specific values.

Example: name:{productName}

totalCountbooleanOptional

If set to true, a total number of sites is returned in a response header.

Default: false

expandstringOptional

Used to expand specific site settings.

Setting	Possible values
payment shipping tax	all active none
mixins	{mixinName} *

Example: payment:all,shipping:active,tax:none,mixin:customerSettings

Responses

200

OK

application/json

Responsestring[]

400Error

application/json

401Error

application/json

403Error

application/json

get

HTTPcURLJavaScriptPython

GET /site/{tenant}/siteslist HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  "UK",
  "FR",
  "main",
  "DE",
  "US"
]