Overview

The Site service helps you mange your sites. Each site is a collection of settings, such as language, currency, shipment, and payment. You can create and manage various site configurations, each of which can be accessed directly with the separate service API endpoint.

Merchants can plug in additional services that implement functionalities of a service provider such as shipping, payment, and tax. Service provider configurations can be fully managed by the merchants while still being partially accessible for the actual service provider. These functionalities can be activated or deactivated depending on the current site requirements.

Additionally, merchants can associate custom configuration options with any site using the mixin mechanism in the Document service.


API Reference

/{tenant}/sites

Manages sites for given tenant.

/{tenant}/sites

get

Retrieves the list of site configurations.

post

Creates a site configuration.

Requires scope hybris.site_manage.

/{tenant}/sites/{code}

Manages a single site for given tenant.

get

Retrieves complete configuration data for a site.

put

Updates site configuration (fully or partially).

In case of the full update, the expand parameter should be provided with a value matching the one used to retrieve a site. The information for mixins and service provider configuration will be updated only if the appropriate expand options are provided. This is necessary in order to prevent from accidental data loss.

Requires scope hybris.site_manage.

delete

Deletes site configuration.

The default site configuration cannot be deleted.

Requires scope hybris.site_manage.

/{tenant}/sites/{code}/shipping

Manages shipping configurations of the given site.

get

Retrieves the list of shipping configurations of the given site.

post

Creates a shipping configuration for the given site.

Requires scope hybris.site_manage.

/{tenant}/sites/{code}/shipping/{id}

Manages a single shipping configuration of the given site.

get

Retrieves details of the given shipping configuration of the given site.

put

Updates the given shipping configuration of the given site.

Requires scope hybris.site_manage.

delete

Deletes the configuration.

/{tenant}/sites/{code}/payment

Manages payment configurations of the given site.

get

Retrieves the list of payment configurations of the given site.

post

Creates a payment configuration for the given site.

Requires scope hybris.site_manage.

/{tenant}/sites/{code}/payment/{id}

Manages a single payment configuration of the given site.

get

Retrieves details of the given payment configuration of the given site.

put

Updates the given payment configuration of the given site.

Requires scope hybris.site_manage.

delete

Deletes the configuration.

/{tenant}/sites/{code}/tax

Manages tax configurations of the given site.

get

Retrieves the list of tax configurations of the given site.

post

Creates a tax configuration for the given site.

Requires scope hybris.site_manage.

/{tenant}/sites/{code}/tax/{id}

Manages a single tax configuration of the given site.

get

Retrieves details of the given tax configuration of the given site.

put

Updates the given tax configuration of the given site.

Requires scope hybris.site_manage.

delete

Deletes the configuration.

/{tenant}/sites/{code}/mixins

Manages custom data (mixins) associated with the given site.

get

Retrieves a list of all custom configuration objects for the site.

post

Creates a new custom configuration object for the site.

Requires scope hybris.site_manage.

/{tenant}/sites/{code}/mixins/{name}

Manages a single custom data item (mixin) associated with the given site.

get

Retrieves custom configuration object with given name.

put

Updates custom configuration object with given name (fully or partially).

Requires scope hybris.site_manage.

delete

Deletes the given custom configuration object.

Requires scope hybris.site_manage.


Events

For more information about events, see the PubSub service documentation.

TopicDescriptionPayloadExample
hybris.site.site-createdSite createdschema
payload='{"code": "main"}'
hybris.site.site-modifiedSite modifiedschema
payload='{"code": "main"}'
hybris.site.site-deletedSite deletedschema
payload='{"code": "main"}'


Scopes in the Site Service

Scopes let you specify exactly what type of permissions you need to access resources and operations in the Site service.

This table presents all the scopes currently supported by the Site service.

ScopeDescription
hybris.site_manageUse this scope to get full access to all operations on resources. All operations that create, modify, or delete site configurations require this scope. It is also required to access inactive sites, service configurations, or the restricted part of a service configuration.

For more information about the authorization and authentication used in SAP Hybris services, and also about the scopes in general, see:


Site Configurations

The Site service manages site configurations. Each site configuration is a collection of several settings, such as language, currency, shipment, and payment.

Multiple sites can be defined at the same time. Some of these sites can be active, while others can be inactive.

Only active sites are returned by default. To access inactive sites:

  • You must use the hybris.site_manage scope.
  • The includeInactive query parameter must be set to true.

The site has an attribute named homeBase that contains the physical address of the place where the items are shipped from. This data is required for proper shipment and tax calculation.

Although full address data can be provided, only country, zipCode, and state (if applicable) are required. The country and state should be given as a code, not a name, in order for the payment and tax service to properly recognize the region.

Access sites

  • Each site can be accessed directly with the /{tenant}/sites/{code} endpoint.
  • One of the sites can be marked as the default site.
  • The default site is always accessible with /{tenant}/sites/default, independent of its actual code. You cannot use default as a site code.

This is an example of a site configuration:

{
  "code": "china",
  "name": "Chinese Site",
  "active": true,
  "default": true,
  "defaultLanguage": "zn",
  "languages": [
    "en",
    "zn"
  ],
  "currency": "CNY",
  "homeBase": {
    "address": {
      "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"
    },
    "location": {
      "latitude": 31.5316133,
      "longitude": 121.1646007
    }
  },
  "shipToCountries" : [
    "CN"
  ],
  "shipping": [
    ...
  ],
  "payment": [
    ...
  ],
  "tax": [
    ...
  ],
  "mixins": {
    ...
  }
}

Query sites

When querying the site list, only basic site information is provided. Shipping, payment, tax, and mixins are not included.

The results can be expanded with the expand query parameter. You can control the expansion of shipping, payment, tax, and mixin information separately.

When querying a site, basic information about shipping, payment, and tax is provided. The following example does not have a configuration attribute:

"payment": [
  {
    "id": "stripe",
    "name": "stripe Payment Service",
    "serviceType": "urn:x-yaas:service:payment",
    "serviceUrl": "https://api.beta.yaas.io/payment-stripe/v1",
    "active": true
  },
  {
    "id": "paypal",
    "name": "PayPal Payment Service",
    "serviceType": "urn:x-yaas:service:payment",
    "serviceUrl": "https://api.beta.yaas.io/payment-paypal/v1",
    "active": true
  }
]

This example uses the expand parameter to request more data.

"payment": [
  {
    "id": "stripe",
    "name": "stripe Payment Service",
    "serviceType": "urn:x-yaas:service:payment",
    "serviceUrl": "https://api.beta.yaas.io/payment-stripe/v1",
    "active": true,
    "configuration": {
      "public": {
        "option1": "some value",
        "option2": 34
      },
      "restricted": {
        "secredOption": "confidential"
      }
    }
  },
  {
    "id": "paypal",
    "name": "PayPal Payment Service",
    "serviceType": "urn:x-yaas:service:payment",
    "serviceUrl": "https://api.beta.yaas.io/payment-paypal/v1",
    "active": true,
    "configuration": {
      "public": {
        "option1": "some value",
        "option2": 34
      },
      "restricted": {
        "secredOption": "confidential"
      }
    }
  }
]

Retrieving detailed information

Retrieving detailed information is a sequence of these steps:

  1. By default, the details are hidden and only basic information is retrieved and presented.
  2. Next, users can select a particular site and see a list of configured providers for shipments, payment, and so on.
  3. Eventually, users gain access to the selected provider configuration.


Default Site

Create a default site

With the Site service, you can have multiple sites. One of these sites can be marked as the default site. The default site is the site that users are initially redirected to before they even start configuring their personal site preferences.

The default site is always available, even if it has not been explicitly created. This site is automatically created in case you make a GET request on these resources:

  • /{tenant}/sites/default: You have queried a default site.
  • /{tenant}/sites: You have listed available sites.

The {tenant} URL path parameter should be replaced by the actual tenant of your choice. The default property is set to true in an automatically created site configuration.

The default site must always exist. You can add a new site or remove an existing site as long as it is not marked as the default site. Trying to remove a default site is forbidden and returns an error code of 400.

Import project settings

The first time a GET operation is performed on the /{tenant}/sites/default resource, a default site is created if one does not already exist.

  • The code for this site is set to main.
  • The languages property for this site is taken from the defined project languages. If one is not available, the property is set to ["en"]. * The currency property is taken from the default project currency. If one is not available, the property is set to USD.


Countries for Shipment

The Site service manages site configurations. Each site configuration is a collection of several settings, such as language, currency, shipment, and payment.

Merchants can set the shipToCountries attribute to define the list of countries to which ordered goods can be shipped.

Each position in the list, defined by the shipToCountries attribute, should be the ISO2 country code. If a position in the list does not contain the ISO2 country code, then the request fails and a 400 Bad Request error is returned.

If the value of the shipToCountries attribute is not explicitly set, a default value can be used. The default value is based on the homebase country defined in the site configuration.


Site Languages Configuration

As a seller, you can configure many different languages for a site by adding a list of languages in the site configuration. The list should include codes for all the languages that the site is going to support. The languages property includes a list similar to this:

"languages": [
        "en",
        "de"
]

Default language

One language in the list can be selected as the default language. This is the first language used to display the localized content for customers who are browsing the site. The default language can be changed to another language at any time. To do so:

  • Perform a PUT request on /{tenant}/sites/{code}, where {tenant} is the current tenant and {code} is replaced with a code of the site to be updated.
  • Update the site configuration with the required values of the languages and defaultLanguage properties. Then, send the updated site configuration with your request:
    "defaultLanguage": "en",
    "languages": [
          "en",
          "de",
          "fr"
    ]
    

If the defaultLanguage property is not set in the site configuration, the first language in the languages list is used as the default language.

Simple validation

When you use a POST or PUT method on the site configuration for the language settings, make sure that the default language is included in the list of configured languages. You cannot set a defaultLanguage property to a language that is not included in the languages property. For example, this request results in an error because the default language of en is not included in the list of configured languages:

"defaultLanguage": "en",
"languages": [
        "de",
        "pl",
        "es"
]

If the default language is not present in the language list, an error code of 400 Bad Request is returned.


Service Providers

The Site service stores the configuration of the pluggable services that can implement shipping, payment, and tax functionality. The configuration of these service providers is separated into two parts:

  • public: This is part of the active site configuration and can be read by anyone.
  • restricted: The restricted part can only be accessed by users having a required permissions level.
Merchants, shop owners, and sellers who configure the Site service have unrestricted, full access to all configuration settings, including restricted configuration parts.

The service accepts any JSON object as a configuration. For example:

"configuration": {
  "public": {
    "option1": "some value",
    "option2": 34
  },
  "restricted": {
    "securedOption": "confidential"
  }
}

Each service provider is identified by two attributes:

  • serviceType: Uniquely identifies the type of the service interface, such as urn:x-yaas:service:shipping for the standard YaaS shipping API.
  • serviceUrl: Points to the location of the service. How you call the service at that URL is determined by the serviceType.

Service providers can be activated or deactivated. Multiple providers can be active for payment and shipping service providers, but only one tax service provider can be active.

Each service provider configuration can be accessed directly through the API endpoints:

  • /{tenant}/sites/{code}/shipping/{id}
  • /{tenant}/sites/{code}/payment/{id}
  • /{tenant}/sites/{code}/tax/{id}

Since the configurations include a restricted part, they should not be passed directly to the service, such as by the Checkout service. Only the URL to the configuration or site ID and configuration ID should be passed.


Tax Provider Configuration

Each site can have multiple tax service providers defined in the site configuration. The tax service providers can be activated or deactivated.

Currently, when a tax service provider becomes active for a site, the rest of the tax service providers are automatically deactivated. For any site, only one tax service provider can be active. Here are some possible scenarios:

  • When an active tax provider is added or an inactive tax provider is made active in a site which already contains a list of tax providers, all other tax providers are deactivated.
  • When a site is added or updated with a list of tax providers which contain multiple active tax providers, it is regarded as an invalid request and an error code of 400 Bad Request is returned.
  • When retrieving the existing tax providers that were persisted before (when multiple active tax providers were allowed), only the first active tax provider is returned as active while the other providers are returned as inactive.


Custom Site Configuration with Mixins

You can associate custom settings included in mixins with the site configurations. This feature is supported by the mixins mechanism, provided by the Document service. A particular mixin can be referenced by the URL, such as /{tenant}/sites/{code}/mixins/{name}, in which:

  • {tenant}: The name of the current tenant.
  • {code}: Unique identifier of the site configuration to which the mixin belongs. A special case of this parameter value is default, which is used to reference the default site.
  • {name}: The mixin name.

Manage custom configurations

As an authorized seller, you can manage custom settings for the site configuration with these endpoints:

  • /sites/{code}/mixins
    • Create new custom settings with the POST method.
    • List all existing custom configurations for a site with the GET method.
  • /sites/{code}/mixins/{name}
    • Retrieve details of any particular mixin assigned to the site configuration with the GET method.
    • Update properties of a single mixin with the PUT method. The Site service also supports the partial=true query parameter to enable partial updates.
    • Remove any particular mixin with the DELETE method.
You can also retrieve mixins, together with the whole site configuration, by using the expand query parameter while using the GET method on the /sites/{code} resource, where the {code} parameter denotes the site configuration.


Extend Site Information

About mixins

In the Site service, mixins are supported by the following methods and endpoints:

  • GET: /{tenant}/sites/{code}/mixins
  • GET and PUT: /{tenant}/sites/{code}/mixins/{mixinName}
  • POST: /{tenant}/{sites}
  • GET and PUT: /{tenant}/{sites}/{code}

There is a schema required for each mixin. The schema is responsible for validating the mixin data. Each mixin cotains an additional metadata block that specifies the schema.

Be aware that the mixin metadata is handled differently by different endpoints. For example:

  • /{tenant}/sites/[{code}]: This endpoint has one metadata attribute with schemas for all mixins, as in the Order and Customer services.
  • /{tenant}/sites/{code}/mixins/[{name}]: This endpoint has a metadata attribute inside the mixin. The metadata attribute has a single schema attribute with a mixin schema URL.

Additionally, there are some complexities that must be considered:

  • POST /{tenant}/sites: Trying to POST a new site with a mixin that does not have the metadata would result in a validation fail.
  • GET and PUT /{tenant}/sites/{code}?expand=mixin:\*: A mixin is returned on GET, but the metadata section is returned empty. So, if you try to update the site using this endpoint, there would be a problem, since the current implementation requires metadata and a schema. As a result, validation would fail.

These cases are relevant only for the existing sites which already have some mixins. This will not happen for new sites and new mixins, because such data will not pass validation.

Query parameter with mixins

In case of GET requests in the Site service, the expand query parameter can handle the mixins. By default, no mixins are returned. There are two options to include a mixin in the response:

  • mixin:* - To expand the parameter value, which will return all defined mixins.
  • mixin:<mixin name> - To expand the parameter value, which will return only the mixin with the name <mixin name>. However, it is possible to use mixin:<mixin name> multiple times, such as expand=mixin:mixin1,mixin:mixin2.

Mixin schema

Mixins define a set of properties you can add to your site definition. The mixin itself is supported by the Schema service and is always referred from other services by URL. The schema is used to validate the contents of the mixin and is also a unique namespace identifier for the mixin.

You can use a mixin in the Schema service to extend any kind of customer information with these additional properties. These properties are not part of the Customer schema, but rather part of the mixin schema.

The service assumes that the schema content is immutable. If the schema referenced by a URL changes, you can expect some unpredictable results.

Mixin data

Each mixin is a named JSON fragment with an associated JSON schema, which is required.

{
  ...
  "code": "europe",
  "name": "Main European Site",
  "active": true,
  "default": true,
  ...
  "metadata": {
    "mixins": {
      "addressVerification": "https://addressVerification.com/pathToSchema.json"
    }
  } ,
  "mixins": {
    "addressVerification": {
      "url": "http://addressVerification.com"
    }
  }
  ...
}

The metadata attribute specifies which mixins can be included. You must always add the metadata property that defines the mixin alias and binds it to the URL to the mixin JSON-formatted definition. You can create the alias as you like. When you use the mixin, it is important to always take the mixin alias you defined in the metadata section. Also, you must have the mixins property, which can store properties from multiple mixins, each one referred by its alias.

Mixin validation

The service validates that the mixin data adheres to the schema. If the mixin does not validate, or if there is no schema declaration for a mixin, a validation is returned with HTTP status code of 400 with detailed information about the error in the response body.


Create Site Configuration

Request

To create a new site configuration, you need:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters
    • {tenant}: The name of the current tenant.

This is the configuration sample you send with your POST request. It should contain all the necessary properties, including those of the service providers.

{
    "code": "china",
    "name": "Chinese Site",
    "active": true,
    "default": true,
    "defaultLanguage": "zn",
    "languages": [
      "en",
      "zn"
    ],
    "currency": "CNY",
      "homeBase": {
        "address": {
        "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"
      },
      "location": {
        "latitude": 31.5316133,
        "longitude": 121.1646007
      }
    },
    "shipToCountries" : [
      "CN"
    ],
    "shipping": [
        {
            "id": "UPS",
            "name": "UPS Shipping Service",
            "serviceType": "urn:x-yaas:service:shipping",
            "serviceUrl": "https://api.beta.yaas.io/shipping-ups/v1",
            "active": true,
            "configuration": {
                "public": {
                    "option1": "some value",
                    "option2": 34
                }
            }
        },
        {
            "id": "FedEx",
            "name": "Fedex Shipping Service",
            "serviceType": "urn:x-yaas:service:shipping",
            "serviceUrl": "https://api.beta.yaas.io/shipping-fedex/v1",
            "active": false
        }
    ],
    "payment": [
        {
            "id": "stripe",
            "name": "stripe Payment Service",
            "serviceType": "urn:x-yaas:service:payment",
            "serviceUrl": "https://api.beta.yaas.io/payment-stripe/v1",
            "active": true,
            "configuration": {
                "public": {
                    "option1": "some value",
                    "option2": 34
                },
                "restricted": {
                    "securedOption": "confidential"
                }
            }
        },
        {
            "id": "paypal",
            "name": "PayPal Payment Service",
            "serviceType": "urn:x-yaas:service:payment",
            "serviceUrl": "https://api.beta.yaas.io/payment-paypal/v1",
            "active": true,
            "configuration": {
                "public": {
                    "option1": "some value",
                    "option2": 34
                },
                "restricted": {
                    "securedOption": "confidential"
                }
            }
        }
    ],
    "tax": [
        {
            "id": "simple",
            "name": "Simple Tax Service",
            "serviceType": "urn:x-yaas:service:tax",
            "serviceUrl": "https://api.beta.yaas.io/tax-simple/v1",
            "active": true
        }
    ]
}

You can create and store multiple site configurations. Some of these sites can be active, while others can be inactive. This is done by modifying the active property in the site configuration.

Each service provider also has an active property, which can be set to true or false. This property enables or disables the current service provider for the whole site configuration. For example, the sample site configuration presented above has two service providers for shipping: UPS and FedEx. UPS is set to be active, and FedEx is inactive. In other words, the active property for UPS is set to true, while the active property for FedEx is set to false.

Response

A successful response includes:

  • A status code of 201, which indicates that the site configuration has been created.
  • A JSON-formatted response that contains the id of the site configuration and a link to the configuration. For example:
    {
      "id": "global",
      "link": "https://api.beta.yaas.io/site/v1/sites/global"
    }
    


Retrieve Multiple Site Configurations

Request

To retrieve site configurations in the tenant, you need:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
  • URL Query Parameters:
    • pageNumber: Displays the requested result page.
    • pageSize: Defines the number of retrieved items per page.
    • includeInactive: If set to true, all configurations are returned. If set to false, the results only include active site configurations.
    • totalCount: Returns the total number of objects in the collection fulfilling the criteria together with the response. This number is returned in the hybris-count header.

Response

A successful response includes:

  • A status code of 200, which indicates that the site configurations have been retrieved.
  • The hybris-count header, which includes the number of objects that fulfilled the criteria. This is only returned if you set the totalCount query parameter.


Remove Site Configuration

Request

You can remove any site configuration stored in the current tenant except the default configuration. To remove a non-default site configuration, you need:

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
    • {code}: The unique code of the site configuration.

Response

A successful response includes a status code of 204, which indicates that the site configuration has been removed.


Update Site Configuration

Request

To update a site configuration, you need:

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
    • {code}: The unique code of the site configuration. You can use a value of default to reference the default site.
  • Query Parameter:
    • partial: If the partial query parameter is set to true, a partial update is performed.

You can modify the active property in the site configuration to enable and disable site configurations. This flag cannot be set to false for the default site.

Each service provider has an active property, which can be set to true or false. This enables or disables the current service provider for the entire site configuration. For example, the sample site configuration presented above has two service providers for shipping: UPS and FedEx. UPS is set to be active, while FedEx is inactive. In other words, the active property for UPS is set to true, while the active property for FedEx is set to false.

Response

A successful response includes a status code of 200, which means the site configuration has been updated.


Retrieve Single Site Configuration

Request

You can retrieve a site configuration stored in the current tenant. To do so, you need:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters
    • {tenant}: The name of the current tenant.
    • {code}: The unique code of the site configuration. You can use a value of default to reference the default site.

Response

A successful response includes a status code of 200, which indicates that the site configuration has been retrieved.

The body contains the details of the retrieved configuration. For example:

{
    "code": "china",
    "name": "Chinese Site",
    "active": true,
    "default": true,
    "defaultLanguage": "zn",
    "languages": [
        "en",
        "zn"
    ],
    "currency": "CNY",
        "homeBase": {
            "address": {
            "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"
        },
        "location": {
            "latitude": 31.5316133,
            "longitude": 121.1646007
        }
    },
    "shipToCountries" : [
        "CN"
    ],
    "shipping": [
        {
            "id": "UPS",
            "name": "UPS Shipping Service",
            "serviceType": "urn:x-yaas:service:shipping",
            "serviceUrl": "https://api.beta.yaas.io/shipping-ups/v1",
            "active": true,
            "configuration": {
                "public": {
                    "option1": "some value",
                    "option2": 34
                }
            }
        },
        {
            "id": "FedEx",
            "name": "Fedex Shipping Service",
            "serviceType": "urn:x-yaas:service:shipping",
            "serviceUrl": "https://api.beta.yaas.io/shipping-fedex/v1",
            "active": false
        }
    ],
    "payment": [
        {
            "id": "stripe",
            "name": "Stripe Payment Service",
            "serviceType": "urn:x-yaas:service:payment",
            "serviceUrl": "https://api.beta.yaas.io/payment-stripe/v1",
            "active": true,
            "configuration": {
                "public": {
                    "option1": "some value",
                    "option2": 34
                },
                "restricted": {
                    "securedOption": "confidential"
                }
            }
        },
        {
            "id": "paypal",
            "name": "PayPal Payment Service",
            "serviceType": "urn:x-yaas:service:payment",
            "serviceUrl": "https://api.beta.yaas.io/payment-paypal/v1",
            "active": true,
            "configuration": {
                "public": {
                    "option1": "some value",
                    "option2": 34
                },
                "restricted": {
                    "securedOption": "confidential"
                }
            }
        }
    ],
    "tax": [
        {
            "id": "simple",
            "name": "Simple Tax Service",
            "serviceType": "urn:x-yaas:service:tax",
            "serviceUrl": "https://api.beta.yaas.io/tax-simple/v1",
            "active": true,
            "configuration": {
                "public": {
                    "option1": "some value",
                    "option2": 34
                },
                "restricted": {
                    "securedOption": "confidential"
                }
            }
        },
        {
            "id": "avalara",
            "name": "Avalara Tax Service",
            "serviceType": "urn:x-yaas:service:tax",
            "serviceUrl": "https://api.beta.yaas.io/tax-avalara/v1",
            "active": true,
            "configuration": {
                "public": {
                    "option1": "some value",
                    "option2": 34
                },
                "restricted": {
                    "securedOption": "confidential"
                }
            }
        }
    ]
}


Add Service Provider Configuration

Sellers can add a configuration of any service provider through the API endpoints.

Request

To add a configuration of a new service provider, you need:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}/{service provider}
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
    • {code}: The code of the site configuration where the service provider belongs.
    • {service provider}: The name of the service provider: shipping, payment, or tax. For example:
      • /{tenant}/sites/{code}/shipping
      • /{tenant}/sites/{code}/payment
      • /{tenant}/sites/{code}/tax

This is an example of a request body that adds two shipping service providers to the site configuration:

[
    {
        "id": "UPS",
        "name": "UPS Shipping Service",
        "serviceType": "urn:x-yaas:service:shipping",
        "serviceUrl": "https://api.beta.yaas.io/shipping-ups/v1",
        "active": true
    },
    {
        "id": "FedEx",
        "name": "Fedex Shipping Service",
        "serviceType": "urn:x-yaas:service:shipping",
        "serviceUrl": "https://api.beta.yaas.io/shipping-fedex/v1",
        "active": true
    }
]
Service providers can be activated or deactivated. There can be multiple active payment and shipping service providers, but there can only be one active tax service provider.

Response

A successful response includes a status code of 201, indicating that the service provider configuration has been added. In this example, two shipping service providers are added to the site configuration: UPS and FedEx.

The response body includes the service provider id and the link to its configuration:

[
    {
        "id": "ups",
        "link": "https://api.beta.yaas.io/site/v1/sites/global/shipping/ups"
    }.
    {
        "id": "fedex",
        "link": "https://api.beta.yaas.io/site/v1/sites/global/shipping/fedex"
    }
]


Retrieve All Service Provider Configurations

Sellers can retrieve all service provider configurations.

Request

To retrieve all configurations of a certain type, you need:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}/{service provider}
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
    • {code}: The code of the site configuration where the service provider belongs.
    • {service provider}: The name of the required service provider: shipping, payment, or tax. For example:
      • /{tenant}/sites/{code}/shipping
      • /{tenant}/sites/{code}/payment
      • /{tenant}/sites/{code}/tax
  • Query Parameter:
    • includeInactive: If set to true, all configurations are returned. If set to false, the results only include active shipping provider configurations. You need a proper scope to see both active and inactive configurations.
    • expand: Use this query parameter to get additional data, including information about all defined service providers, such as shipping: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}?expand=shipping:all

Response

A successful response includes a status code of 200, which indicates that the service provider configurations have been retrieved.

In this example, two shipping service providers are retrieved, both of which are active.

[
    {
        "id": "UPS",
        "name": "UPS Shipping Service",
        "serviceType": "urn:x-yaas:service:shipping",
        "serviceUrl": "https://api.beta.yaas.io/shipping-ups/v1",
        "active": true
    },
    {
        "id": "FedEx",
        "name": "Fedex Shipping Service",
        "serviceType": "urn:x-yaas:service:shipping",
        "serviceUrl": "https://api.beta.yaas.io/shipping-fedex/v1",
        "active": true
    }
]
If there are inactive configurations available, you can include those in the retrieved results by including the includeInactive query parameter in your request URL.


Delete Service Provider Configuration

Sellers can remove any service provider configurations that are no longer needed through the API endpoints.

Request

To remove a selected configuration of an existing service provider, you need:

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}/{service provider}/{id}
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
    • {code}: The code of the site configuration where the service provider belongs.
    • {service provider}: The name of the service provider: shipping, payment, or tax. For example:
      • /{tenant}/sites/{code}/shipping
      • /{tenant}/sites/{code}/payment
      • /{tenant}/sites/{code}/tax
  • {id}: The unique identifier of the service provider configuration. Each service provider has its own separate identifier, which is used to access and manage this one specific configuration, such as https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}/shipping/UPS.

Response

A successful response includes a status code of 204, indicating that the service provider configuration has been removed.


Update Service Provider Configuration

Sellers can manage service provider configurations through the API endpoints to keep them updated.

Request

To retrieve a single service provider configuration, you need:

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}/{service provider}/{id}
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
    • {code}: The code of the site configuration where the service provider belongs.
    • {service provider}: The name of the required service provider: shipping, payment, or tax. Example URLs:
      • /{tenant}/sites/{code}/shipping/{id}
      • /{tenant}/sites/{code}/payment/{id}
      • /{tenant}/sites/{code}/tax/{id}
    • {id}: The unique identifier of the service provider configuration. Each service provider has its own separate identifier, which is used to access and manage this one specific configuration, such as https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}/shipping/UPS.
  • Query Parameter:
    • partial: If the partial query parameter is set to true, a partial update is performed.

This is an example of the request body that deactivates the UPS service provider configuration. The active property is set to false.

{
    "id": "UPS",
    "name": "UPS Shipping Service",
    "serviceType": "urn:x-yaas:service:shipping",
    "serviceUrl": "https://api.beta.yaas.io/shipping-ups/v1",
    "active": false
}

Response

A successful response includes a status code of 200, which indicates that the service provider configuration has been updated.


Retrieve Single Service Provider Configuration

Sellers can retrieve all service provider configurations, or they can retrieve a single service provider configuration using the configuration's unique code.

Request

To retrieve a single service provider configuration, you need:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}/{service provider}/{id}
  • Headers:
    • Authorization: You must provide a proper scope that enables users to perform these operations. These scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see the Authorization section.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
    • {code}: The code of the site configuration where the service provider belongs.
    • {service provider}: The name of the required service provider: shipping, payment, or tax. For example:
      • /{tenant}/sites/{code}/shipping/{id}
      • /{tenant}/sites/{code}/payment/{id}
      • /{tenant}/sites/{code}/tax/{id}
    • {id}: The unique identifier of the service provider configuration. Each service provider has its own unique identifier, which is used to access and manage this one specific configuration, such as https://api.beta.yaas.io/hybris/site/v1/{tenant}/sites/{code}/shipping/UPS.

Response

A successful response includes a status code of 200, which indicates that the requested service provider configuration has been retrieved.

Even if the site configuration includes several service providers, you can retrieve a single specific service provider configuration. In this example, a single configuration of the UPS shipping provider is retrieved:

{
    "id": "UPS",
    "name": "UPS Shipping Service",
    "serviceType": "urn:x-yaas:service:shipping",
    "serviceUrl": "https://api.beta.yaas.io/shipping-ups/v1",
    "active": true,
    "configuration": {
        "public": {w
            "option1": "some value",
            "option2": 34
        },
        "restricted": {
            "securedOption": "confidential"
        }
    }
}


Glossary

TermDescription
mixinCustomizable definition of additional properties for the site. One site definition can use many mixins, and one mixin can be used by many site definitions.
service providerPluggable services, which can implement shipping, payment, and tax functionality.
tenantA tenant is a group of users on a project sharing common access, with specific privileges to a service.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.