Site Settings

Retrieving sites

get

Retrieves a list of site configurations.

Additional scopes info

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

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant 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

application/json

400Error

application/json

401Error

application/json

403Error

application/json

get/site/{tenant}/sites

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
      },
      "timezone": "America/New_York"
    },
    "shipToCountries": [
      "US"
    ],
    "assistedBuying": {
      "storefrontUrl": ""
    },
    "metadata": {
      "mixins": {
        "productSettings": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productSettingsSiteMixIn.v1",
        "generalShopSettings": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/generalShopSettingsSiteMixIn.v10",
        "customerSettings": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/customerSettingsSiteMixIn.v3",
        "orderProcessSettings": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/orderProcessSettingsSiteMixIn.v7",
        "couponSettings": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/couponSettingsSiteMixIn.v4",
        "feeService": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/siteFeeService.json",
        "imageSize": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/imageSize.v6",
        "merchantInfo": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/merchantAddressMixin.v10"
      },
      "version": 14
    },
    "default": true
  }
]

Creating a site

post

Creates a new site configuration.

Required scopes

This endpoint requires the following scopes:

: Needed to manage sites.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Body

Information about the site.

codestringRequired

Site unique identifier.

Pattern: ^[^\s#]+$

namestringRequired

Site name.

activebooleanOptional

Flag indicating whether the site is active.

defaultbooleanOptional

Flag indicating whether the site is the tenant default site.

includesTaxbooleanOptional

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

defaultLanguagestring · min: 2Required

Site's default language, compliant with the IETF BCP-47 standard. Regional variants such as fr-ca are supported.

Pattern: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$

languagesstring[]Required

Languages supported by the site.

Note: The languages must be compliant with the IETF BCP-47 standard. Regional variants such as fr-ca are supported.

currencystring · min: 3 · max: 3Required

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[]Required

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 · enumRequired

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

idstringOptional

Resource identifier.

400Error

application/json

401Error

application/json

403Error

application/json

post/site/{tenant}/sites

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

{
  "code": "uk-store",
  "name": "United Kingdom",
  "active": false,
  "default": false,
  "defaultLanguage": "en",
  "languages": [
    "en"
  ],
  "currency": "GBP",
  "homeBase": {
    "address": {
      "country": "GB",
      "zipCode": "12345"
    },
    "timezone": "Europe/London"
  },
  "shipToCountries": [
    "GB"
  ],
  "mixins": {},
  "metadata": {}
}

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

Retrieving a site

get

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

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant 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

Information about the site.

codestringRequired

Site unique identifier.

Pattern: ^[^\s#]+$

namestringRequired

Site name.

activebooleanOptional

Flag indicating whether the site is active.

defaultbooleanOptional

Flag indicating whether the site is the tenant default site.

includesTaxbooleanOptional

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

defaultLanguagestring · min: 2Required

Site's default language, compliant with the IETF BCP-47 standard. Regional variants such as fr-ca are supported.

Pattern: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$

languagesstring[]Required

Languages supported by the site.

Note: The languages must be compliant with the IETF BCP-47 standard. Regional variants such as fr-ca are supported.

currencystring · min: 3 · max: 3Required

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[]Required

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 · enumRequired

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

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

500

Internal Server Error

application/json

get/site/{tenant}/sites/{siteCode}

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

{
  "code": "uk-store",
  "name": "United Kingdom",
  "active": false,
  "defaultLanguage": "en",
  "languages": [
    "en"
  ],
  "currency": "GBP",
  "homeBase": {
    "address": {
      "zipCode": "12345",
      "country": "GB"
    },
    "timezone": "Europe/London"
  },
  "shipToCountries": [
    "GB"
  ],
  "metadata": {
    "mixins": {},
    "version": 0
  },
  "default": true
}

Fully updating a site

put

Fully updates a specified site 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

This endpoint requires the following scopes:

: Needed to manage sites.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant 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.

codestringRequired

Site unique identifier.

Pattern: ^[^\s#]+$

namestringRequired

Site name.

activebooleanOptional

Flag indicating whether the site is active.

defaultbooleanOptional

Flag indicating whether the site is the tenant default site.

includesTaxbooleanOptional

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

defaultLanguagestring · min: 2Required

Site's default language, compliant with the IETF BCP-47 standard. Regional variants such as fr-ca are supported.

Pattern: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$

languagesstring[]Required

Languages supported by the site.

Note: The languages must be compliant with the IETF BCP-47 standard. Regional variants such as fr-ca are supported.

currencystring · min: 3 · max: 3Required

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[]Required

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 · enumRequired

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.

No content

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

409

Conflict

500

Internal Server Error

put/site/{tenant}/sites/{siteCode}

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

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

No content

Deleting a site

delete

Deletes a specified site.

Important: You cannot delete a site for which the default property is set to true.

Required scopes

This endpoint requires the following scopes:

: Needed to manage sites.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant 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.

No content

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

500

Internal Server Error

delete/site/{tenant}/sites/{siteCode}

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 configuration.

Required scopes

This endpoint requires the following scopes:

: Needed to manage sites.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant 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.

codestringRequired

Site unique identifier.

Pattern: ^[^\s#]+$

namestringRequired

Site name.

activebooleanOptional

Flag indicating whether the site is active.

defaultbooleanOptional

Flag indicating whether the site is the tenant default site.

includesTaxbooleanOptional

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

defaultLanguagestring · min: 2Required

Site's default language, compliant with the IETF BCP-47 standard. Regional variants such as fr-ca are supported.

Pattern: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$

languagesstring[]Required

Languages supported by the site.

Note: The languages must be compliant with the IETF BCP-47 standard. Regional variants such as fr-ca are supported.

currencystring · min: 3 · max: 3Required

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[]Required

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 · enumRequired

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.

No content

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

409

Conflict

500

Internal Server Error

patch/site/{tenant}/sites/{siteCode}

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

{
  "defaultLanguage": "fr-ca",
  "languages": [
    "en",
    "fr-ca"
  ]
}

No content

Retrieving site codes

get

Retrieves a list of site codes.

Additional scopes info

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

Required scopes

This endpoint requires the following scopes:

: Needed to retrieve information about sites.
: Needed to manage sites.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant 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

application/json

Responsestring[]

400Error

application/json

401Error

application/json

403Error

application/json

get/site/{tenant}/siteslist

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

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

PreviousMixins

NextModels

Last updated 10 days ago

Was this helpful?