Initial Tenant Checkout Configuration
Start configuring a fresh tenant to enable your online store quickly and efficiently.
This tutorial guides developers through configuration steps of a fresh Emporix tenant with the aim of enabling checkout functionality in the storefront. Start with a brand new tenant to set up and enable all the required features from scratch.
The steps take you through the following paths:
Tenant setup - Basic tenant and site settings
Data import - Catalog, products, and pricing setup
Customer setup - Test customer and address configuration
Storefront checkout flow - The scenario to make a purchase and complete checkout on the storefront as a customer
After completing the steps you will understand the minimum configuration needed for checkout and how to successfully complete a checkout in the Emporix B2B Commerce Frontend, or a custom storefront solution. The described steps help you achieve a working configuration for the whole checkout flow with simple examples, but you can further extend this configuration for your specific business needs. Consider configuring multiple delivery times (for scheduled deliveries), multiple shipping methods (for different delivery options), multiple payment methods (for customer choice), enhancing product with images and media, as well as brand and label setup.
Prerequisites
To get started, make sure you have:
Emporix Account - an active Emporix tenant created
API keys - credentials to make relevant API calls
We recommend you to be prepared to collect these values as you go. Each step lists where to copy them from.
{{tenant}}
Tenant identifier
Your tenant id
{{client_id}}, {{client_secret}}
Service credentials
Emporix Developer Portal
{{storefront_client_id}}
Storefront client id
Emporix Developer Portal
{{category_id}}
Category id
Create a category response
{{product_id}}
Product id
Create a product response
{{priceModelId}}
Price model id
Create a price model response
{{priceId}}
Price id
Create a price response
{{zoneId}}
Shipping zone id
Create a shipping zone response
{{shipping_method_id}}
Shipping method id
Create a shipping method response
{{cartId}}
Cart id
Create a cart response
Authorization
For the configuration steps (tenant setup, data import, and customer setup), the Service Access Token is required.
Get authorization token
To obtain proper access, send the authorization request to the Requesting a service access token endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
How to enable checkout functionality
Configure a fresh tenant
Follow these steps to provide basic configuration for your tenant, such as payment, site, language, currency, tax, and shipping zones and methods.
There is also a convenient alternative way for initial tenant configuration. You can use the Emporix Terraform Provider to automate the process.
Configure payment method
Create invoice for a minimal setup of payments. To create a new payment method, call the Creating a single payment mode entity endpoint. For real payments, configure a provider-specific mode with its required credentials.
To test the endpoint, open the API reference or check the example of a curl request.
Activate a country, currency and language
You need to activate countries where you want to operate, as well as add relevant currency and language.
Activate a country with the Updating a country request, for example Poland:
To test the endpoint, open the API reference or check the example of a curl request.
You need to activate currencies relevant for the countries where your business operates or relevant to your business model. Ensure currency codes are ISO 4217 compliant. Create a
Polish Zlotycurrency with the Creating a new currency endpoint:
To test the endpoint, open the API reference or check the example of a curl request.
Specify the languages that your business communicates with suppliers and customers. Emporix supports a broad choice of languages, including regional language variants. The tenant's language configuration is stored under the
project_langkey, while site-specific language configuration is stored in thedefaultLanguageandlanguagesfields, inside theSiteobject. To setPolishandEnglishas project languages, use the Updating a configuration endpoint:
To test the endpoint, open the API reference or check the example of a curl request.
Add relevant tax calculation configuration
Tax rates define the checkout calculations relevant to a given country. Create tax classes with rates applicable in Poland using the Creating a new tax configuration endpoint. Ensure your rates reflect the desired gross/net calculation strategy for your storefront.
To test the endpoint, open the API reference or check the example of a curl request.
Create a site
Determine a site by a country you operate in or by a brand you want to sell in your store. Create a PL site for the Polish market by sending a request to the Creating a site endpoint. Include the homeBase address country, which is required for shipping calculations. Keep site, country, currency, tax, and shipping zone aligned.
To test the endpoint, open the API reference or check the example of a curl request.
Configure a shipping zone, method and delivery times
Define where you want to ship your goods and how.
First, set the ship-to location for the site using the Creating a shipping zone. Set as the default zone if needed. Save the
idfrom the response for the next step.
To test the endpoint, open the API reference or check the example of a curl request.
Then, configure a shipping method with the Creating a shipping method endpoint. Save the
idfrom the response for the checkout step.
To test the endpoint, open the API reference or check the example of a curl request.
Define the delivery times and connect them with the shipping information. Use the Creating a delivery time endpoint. The
validateOverlapflag enables checks to see whether delivery time ranges for slots of the same shipping method overlap each other. ThedeliveryWindowIdandslotIdused later in cart creation come from this response.
To test the endpoint, open the API reference or check the example of a curl request.
Import data
Once your tenant and site are ready, it's time to import and organize the project data. Follow the steps to create a basic structure for your products that are to be visible in your store.
Create a category
Define a category or a category hierarchy to make it easier for customers to find the products. Create a Tools category by sending a request to the Creating a new category endpoint. Copy the returned id for catalog assignment.
To test the endpoint, open the API reference or check the example of a curl request.
Create a catalog
A catalog determines which categories and category trees are available on your site or sites. Create a Home catalog and publish it on the PL site. Use the Creating a catalog request. Use the category id from the previous step.
To test the endpoint, open the API reference or check the example of a curl request.
Create a product
Add a product to the database with the Creating a new product endpoint. Copy the product id and yrn from the response for the price and cart steps.
To test the endpoint, open the API reference or check the example of a curl request.
Configure a price
Prices are associated with a particular site, so you can set different price configurations for the same product for each site it is visible at. Setting a price allows you to define a tier structure (BASIC, QUANTITY, etc.).
Create a price model using the Creating a new price model endpoint. Save the returned price model
id.
To test the endpoint, open the API reference or check the example of a curl request.
Create a price for the product on the
PLsite and connect it with the price model by sending a request to the Creating a new price endpoint. Save the returned priceid.
To test the endpoint, open the API reference or check the example of a curl request.
Assign a category
Add the product to a category tree for its better searchability. Call the Assigning a resource to a category.
To test the endpoint, open the API reference or check the example of a curl request.
Define availability
Availability determines stock level of a product for a given site. Define the availability by calling the Creating a new availability for a product.
To test the endpoint, open the API reference or check the example of a curl request.
Set up a customer
The tenant and products are ready, so it's time to add customers who can test out the checkout functionality.
Create a customer
Create a B2B customer with the Creating a customer request, providing basic customer's details. Set active to true if you plan to log in with this account.
To test the endpoint, open the API reference or check the example of a curl request.
Specify a customer's address
Add and assign an address to the customer's profile. You can define separate addresses for shipping and billing purposes, marking them with relevant tags. Use the Adding a customer address endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Storefront checkout flow
The tenant setup is prepared to handle checkout functionality. Now, ensure that your storefront setup (or the Emporix B2B Commerce Frontend) is able to process the data and pass it to the relevant API endpoints.
For storefront flow, authorize a customer:
Anonymous Access Token - for anonymous session and cart creation before login.
Customer Access Token - after login, for cart updates and checkout.
Some checkout endpoints also require saas-token and session-id headers, which you obtain from the login/anonymous session response and should pass through your storefront.
The example checkout flow on the storefront side includes the following steps.
Start an anonymous session
An anonymous session begins when a user enters your storefront, before they choose to log in. Get an anonymous access token with the Requesting an anonymous token endpoint. Pass the Storefront Client ID.
To test the endpoint, open the API reference or check the example of a curl request.
This request creates a new session-context document. The anonymous token is valid for one hour. After that time, refresh it to keep the same session ID associated.
Enable customer login
To allow your customers to authorize themselves, enable the Logging in a customer endpoint on the storefront. Authorize the request with the anonymous_token.
To test the endpoint, open the API reference or check the example of a curl request.
It is also possible for customers to continue to checkout as guest customers, without logging in, so this step can be optional.
This operation returns Customer access token and Customer SaaS token, which convey information about the customer and their activities on the storefront. Use these values for Authorization and saas-token headers in the next steps.
Create a cart
Creating a cart operation gathers the customer's session details, including for anonymous customers. Enable cart creation on the storefront using the Creating a new cart endpoint. The request needs to be authorized with the Customer Access Token or Anonymous Access Token, depending on whether a customer is already logged in. Use the deliveryWindow values from the delivery times response.
To test the endpoint, open the API reference or check the example of a curl request.
Add items to the cart
To allow customers to place some items in the cart, use the Adding a product to cart endpoint. Use the product yrn and price id created earlier.
To test the endpoint, open the API reference or check the example of a curl request.
Enable the price matching mechanism
Price matching allows your customers to find the best price calculated on the fly during their session, including discounts, offers, segments or similar information. To that end, use the Matching prices for session context endpoint in our storefront setup. The request is authorized with the CustomerAccessToken, so make sure you pass that data from the customer entering your store. Call this before checkout when you need to recalculate prices based on session context.
To test the endpoint, open the API reference or check the example of a curl request.
Proceed to checkout
Once the customer wants to finalize the purchase, enable the checkout option. The checkout does several validation checks on the provided data, including cart details, product availability, customer details, payment method, price calculations, shipping information and delivery. The operation creates an order, handles the payment, and closes the cart. To enable checkout operation on your storefront, use the Triggering a checkout endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Verify order creation
As a last step, verify if the order placed by a customer is created accordingly. To display the order details to the customer on the storefront, use the Retrieving order details endpoint. Authorize the request with the customer access token.
To obtain the order details and later send tem to the ERP/CRM system, use the Retrieving sales order details. Authorize the request with the OAuth access token.
As a result, you retrieve all the details related to the placed order, which you can display in the UI.
From there, you can process the order.
To test the endpoint, open the API reference or check the example of a curl request.
Troubleshooting
Missing home base address
Set homeBase.country on the site to match the site country so shipping calculations succeed.
Currency mismatch between tenant and site
Ensure the site currency is active and matches the currency used in prices and carts.
Tax configuration missing for target country
Create a tax configuration for the target country and use matching tax class codes on products and shipping.
Shipping zone not matching customer address
Add the customer’s country/postal range to the shipping zone or set the correct default zone.
Products without prices
Create a price model and price for each product and site before checkout.
Sites not linked to catalogs
Publish the catalog to the site and include the relevant category ids.
For more information, see the following documentation and API references:
Last updated
Was this helpful?