External Products, Pricing and Fees

You can connect an external application or system to fetch products, prices, or fees outside Emporix.

The cart and checkout functionality typically enables customers to purchase items listed in your store's database. During checkout, the system calculates the total price, taking into account the listed prices, shipping costs and any applicable discounts. However, in B2B use cases, you may need to integrate an external system to calculate prices, custom fees or even allow the purchase of products sourced from an external ERP system, bypassing the standard product catalog.

Emporix recognizes that B2B transactions often demand competitive pricing tailored to various factors, such as product relationships, purchase volume, customer loyalty, and more. It also understands that sometimes you might require to calculate additional fees for shipping, freight and more.

To address this, Commerce Engine allows seamless integration with external systems that handle product management, price calculations and custom fee management. By leveraging external applications, businesses can ensure accurate and tailored pricing for each customer, streamline pricing and fee processes, and enhance overall operational efficiency. This can be accomplished by leveraging the extensibility features of the Cart Service.

The extended cart supports the following integration scenarios:

• Third-party pricing for products existing within CE: Prices are calculated externally by other applications and overwrite those set in Commerce Engine.

• Third-party pricing for products not defined within CE: Products from an external system, including their pricing, are added to the cart.

• Products without predefined prices: The cart allows products with no set price to be added making checkout possible, with the final price updated from an external system at the last stage of purchase completion. To cover such a case and proceed with checkout, set temporarily the price value to 0.

• Third-party sourced fees: The products added to the cart might require additional fees to be calculated, such as for example shipping, freight, packaging, large-size load, or more. Calculate additional fees externally and add them at the customer's cart level.

Extended cart flow

The diagram shows the communication between Emporix and an external system that calculates prices or manages product information. The storefront triggers an additional layer, it can be a backend for frontend (BFF) or an external service outside of the Emporix environment. The price calculation happens at that middleware layer by sending a request to an ERP system. Once the data is ready the BFF layer communicates with the Emporix Cart Service directly.

Enabling external products, pricing and fees

Enabling an external service to provide product, pricing and fee information at the cart level requires the following steps:

1. Get the cart.cart_manage_external_prices scope to handle external system communication.

   a. Go to the Emporix Developer Portal, Manage API Keys section.

   b. In the Custom API, use Add scopes or Add more groups option.

   c. Add a group name of your choice, and under Cart, select the cart.cart_manage_external_prices scope.

   

   d. Confirm with Generate.

   Now, you can use the generated API keys to allow communication between the Cart Service and an external system for managing pricing.

Never grant access to these API keys to the end customers as it may lead to security risk of faking your price data.

1. Turn on the enableExternalPrices setting. You can achieve that in the Management Dashboard or through the Configuration Service:

   • In the Management Dashboard, go to the Settings -> System Preferences. Set the value to true for the Allow fetching external prices setting.

   • In the Configuration Service, add the following configuration:

     {
       "key": "enableExternalPrices",
       "value": true,
       "version": 1,
       "secured": false
     }

2. Use your dedicated Backend-for-Frontend (BFF) layer or an external service responsible for managing pricing, fees and/or products on your side. This layer is to be positioned in between the storefront and the Emporix Cart Service. Ensure that this BFF is properly configured, as the generated API key with the scope for managing external pricing serves as an authorisation token. The token enables direct communication with the Cart Service to update your storefront customers' carts.

When external pricing is enabled, it is essential to ensure the accuracy of the external prices from your price engine, as CE does not perform price validation in such cases.

Managing carts with external product, pricing, or fee information

Once you've enabled the external system in Emporix environment, and configured the external service properly, you're able to use the external service to handle price and fee calculation or product management at a customer's cart level. When a customer creates a cart, you're able to add custom product, pricing and fee data that comes from another service by using the Emporix Cart Service API. Modifying the customer's cart is possible by making a call to the Adding a product to cart endpoint, defining the external sourcing. The request payload has to define the itemType property and set it to EXTERNAL. This ensures the CE cart is able to read data coming from external applications. Include the price details and also tax details relevant for the pricing. See examples of how you can construct such a request.

External prices

• Overwriting a product's price from an external source

{
    "itemYrn": "urn:yaas:saasag:caasproduct:product:mytenant;1600A016BF",
    "itemType": "EXTERNAL",
    "price": {
        "effectiveAmount": 2.0,
        "originalAmount": 2.0,
        "currency": "EUR"
    },
    "tax": {
        "name": "STANDARD",
        "rate": 10,
        "grossValue": 2.0,
        "netValue": 1.82
    },
    "quantity": 1
}

Notice that to overwrite a product that is available in CE product catalog, you need to provide the relevant itemYrn property.\

External products

• Adding a product from an external source, outside CE catalog, including external price calculation

{
  "itemType" : "EXTERNAL",
  "product": {
    "id": "myTestId",
    "name": "myExternalProduct",
    "description": "testExternalProduct",
    "sku": "sku",
    "images": [
                {
                   "id": "imageid",
                   "url": "imageURL"
                }
    ]
  },
  "price": {
    "effectiveAmount": 2.00,
    "originalAmount": 2.00,
    "currency": "EUR"
  },
  "tax": {
    "name": "STANDARD",
    "rate": 10,
    "grossValue": 2.00,
    "netValue": 1.82
  },
  "quantity": 1
}

• Adding a product without a price

{
    "itemYrn": "urn:yaas:saasag:caasproduct:product:mytenant;1600A016BF",
    "itemType": "EXTERNAL",
    "price": {
        "effectiveAmount": 0.0,
        "originalAmount": 0.0,
        "currency": "EUR"
    },
    "tax": {
        "name": "STANDARD",
        "rate": 10,
        "grossValue": 0.0,
        "netValue": 0.0
    },
    "quantity": 1
}

To achieve completing checkout with products without price defined, define the price to 0.0 value. You can then overwrite the pricing at a later stage, calculating it according to the relevant factors you want to take into account.

External fees

• Adding an external fee

{
    "itemYrn": "urn:yaas:saasag:caasproduct:product:mytenant;1600A016BF",
    "externalFees": [
        {
            "name": {
                "en": "Freight Fee"
            },
            "feeType": "ABSOLUTE",
            "feeAbsolute": {
                "amount": 5.00,
                "currency": "EUR"
            }
        }
    ]
}

It is possible to combine standard fees with external fees. Depending on your context, you could add a standard fee to one product in a cart and an external fee to another one. However, adding a custom external fee prevails over the standard fee defined for a specific product in the Fee Service.

The calculated fees are visible in the order summary in the Management Dashboard.

For more information, see the Cart Service Tutorial.