Checkout Tutorial
As the checkout functionality is the core of your commerce operations, make sure it works properly in your online store.
The checkout service validates data that comes from different points in the system: cart, order, payment, delivery zone, shipping method, tax, and customer. Therefore, you need proper configuration of these services to make checkout work as expected. This tutorial guides you through the basic setup of the checkout service.
How to configure the Checkout Service
Gather information about a customer's session on the storefront
You need details about the customer's access and session tokens as these details influence the checkout process.
When a user enters your storefront, before they choose to log in, an anonymous user session is created.
Get an anonymous access token by sending a request to the Requesting an anonymous token endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X GET \
'https://api.emporix.io/customerlogin/auth/anonymous/login?tenant={tenant}&client_id={client_id}'Log the customer in and send an authorization request to the Requesting a customer token endpoint.
You can skip this step and continue with the checkout process as a guest customer without the need to log in.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/customer/{tenant}/login' \
-H 'Authorization: string' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"password": "Qwurmdch673;'\''"
}'This operation returns the customer's access token and Saas token, which convey information about the customer and their activities on the storefront. You might need these details in subsequent steps to get a proper authorization when a customer is logged in.
Add tax configuration
Each country that you operate in may have different tax rules for different products and services. Add relevant configuration to calculate taxes accordingly.
Add tax configuration by sending a request to the Creating a new tax configuration endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/tax/{tenant}/taxes' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Language: string' \
-H 'Content-Type: application/json' \
-d '{
"location": {
"countryCode": "DE"
},
"taxClasses": [
{
"code": "STANDARD",
"name": {
"en": "Standard"
},
"order": 0,
"rate": 19,
"isDefault": true
},
{
"code": "REDUCED",
"name": {
"en": "Reduced"
},
"order": 1,
"rate": 7
},
{
"code": "ZERO",
"name": {
"en": "Zero"
},
"order": 2,
"rate": 0
}
]
}'Define the delivery zone, method, and time
Delivery zone is the area where you ship your goods to. You can define a country, or a zip code that you operate within. Delivery method is dependant on a specific site and delivery zone.
Define the delivery zone by sending a request to the Creating a shipping zone endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/shipping/{tenant}/{site}/zones' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Language: fr' \
-H 'Content-Type: application/json' \
-d '{
"shipTo": [
{
"country": "DE",
"postalCode": "70190"
}
],
"name": "Zone 1",
"id": "zone1",
"default": true
}'Specify how the goods can be shipped to a customer by sending a request to the Creating a shipping method endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/shipping/{tenant}/{site}/zones/{zoneId}/methods' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Language: fr' \
-H 'Content-Type: application/json' \
-d '{
"id": "fedex-2dayground",
"name": "FedEx 2Day",
"active": true,
"maxOrderValue": {
"amount": 5000,
"currency": "EUR"
},
"fees": [
{
"minOrderValue": {
"amount": 0,
"currency": "EUR"
},
"cost": {
"amount": 10,
"currency": "EUR"
}
},
{
"minOrderValue": {
"amount": 50,
"currency": "EUR"
},
"cost": {
"amount": 9,
"currency": "EUR"
},
"shippingGroupId": "group1"
},
{
"minOrderValue": {
"amount": 200,
"currency": "EUR"
},
"cost": {
"amount": 8,
"currency": "EUR"
},
"shippingGroupId": "group2"
}
]
}'Define delivery time that will be matched with the delivery method and zone by sending the request to the Creating a delivery time endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/shipping/{tenant}/delivery-times?validateOverlap=true' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"siteCode": "main",
"name": "deliverytime1",
"isDeliveryDay": true,
"zoneId": "zone1",
"day": {
"weekday": "FRIDAY"
},
"isForAllZones": false,
"timeZoneId": "Europe/Warsaw",
"deliveryDayShift": 0,
"slots": [
{
"shippingMethod": "method1",
"deliveryTimeRange": {
"timeFrom": "10:00",
"timeTo": "12:00"
},
"cutOffTime": {
"time": "2023-06-12T06:00:00.000Z",
"deliveryCycleName": "morning"
},
"capacity": 100
}
]
}'Add products to your store
To create and add multiple products to your store, send the request to the Creating multiple products endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/product/{tenant}/products/bulk?skipVariantGeneration=false&doIndex=true' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Language: string' \
-H 'Content-Type: application/json' \
-d '{}'Create a price model and connect it to products
Price model defines your pricing strategy. You can specify how you want to go about price tiers and selling volumes.
To define a price model send a request to the Creating a new price model endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/price/{tenant}/priceModels' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Language: string' \
-H 'Content-Type: application/json' \
-d '{
"includesTax": true,
"includesMarkup": true,
"name": "Piece price model",
"description": "Sample description",
"tierDefinition": {
"tierType": "BASIC",
"tiers": [
{
"minQuantity": {
"quantity": 0,
"unitCode": "pc"
}
}
]
},
"measurementUnit": {
"quantity": 0,
"unitCode": "pc"
}
}'Create a price for a specific product by sending a request to the Creating a new price endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
url -i -X POST \
'https://api.emporix.io/price/{tenant}/prices' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Language: string' \
-H 'Content-Type: application/json' \
-d '{
"id": "6245aa0a78a8576e338fa9c4",
"itemId": {
"itemType": "PRODUCT",
"id": "5f5a3a365bac380024b93c45"
},
"currency": "EUR",
"location": {
"countryCode": "DE"
},
"priceModelId": "6245a8f578a8576e338fa9c3",
"restrictions": {
"siteCodes": [
"1111"
]
},
"tierValues": [
{
"priceValue": 15.99
},
{
"priceValue": 14.99
},
{
"priceValue": 13.99
}
]
}'Match the price by session context to allow your customers find the best price based on information retrieved from the session context.
The following request requires using the customer's access token for authorization, either anonymous or logged in, as the response contains the bearer's information.
Send the request to the Matching prices for session context endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/price/{tenant}/match-prices-by-context' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"items": [
{
"itemId": {
"itemType": "PRODUCT",
"id": "5f5a39d95bac380024b93c24"
},
"quantity": {
"quantity": 1,
"unitCode": "kg"
}
}
]
}'Create a cart
The following requests require using the customer's access token for authorization, either anonymous or logged in, as the response contains the bearer's information.
You have to enable an option to create a cart on your site while a customer is browsing through your products. Creating a cart takes care of things like gathering customer's session details, even anonymous, or setting up a proper cart's currency for final calculations at checkout. There are two options to create carts using API:
Create a cart by sending a request to the Creating a new cart endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/cart/{tenant}/carts' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'saas-token: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI2MTQ0MzU2MyIsImV4cCI6MTY5Nzk3MDUyOH0.F0b5jr6KeSoBCj-suTLuasmydaJEudc1ZrESkQXSCGk' \
-H 'session-id: string' \
-d '{
"customerId": "87413250",
"siteCode": "main",
"type": "shopping",
"deliveryWindow": {
"id": "5b5572a61cf31a000f31eee4",
"deliveryDate": "2023-06-06T12:00:00.000Z",
"slotId": "5678-8756-3321-1234"
},
"channel": {
"name": "storefront",
"source": "https://your-storefront.com/"
},
"currency": "EUR"
}'Create a cart by sending a
GETrequest withcreate=trueparameter to the Retrieving a cart's details by criteria endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/cart/{tenant}/carts' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'saas-token: string' \
-H 'session-id: string' \
-d '{
"siteCode": "main",
"currency": "EUR",
"type": "shopping",
"channel": {
"name": "storefront",
"source": "https://your-storefront.com/"
},
"sessionValidated": true
}'Add items to the cart by sending the request to the Creating a new cart endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/cart/{tenant}/carts/{cartId}/items?siteCode=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"itemYrn": "{productYrn}",
"price": {
"priceId": "{priceId}",
"effectiveAmount": 0.3582,
"originalAmount": 0.3582,
"currency": "EUR"
},
"quantity": 6
}'Define payment methods
You can configure payment methods in the Payment Gateway Service. Check the available options in the Payment Systems documentation.
Trigger the checkout
To complete the checkout, there are two options:
The customer has to be logged in to the storefront and then the following request requires using the customer's access token for authorization - see Gather information about a customer's session on the storefront.
The customer continues as a guest without logging in - the
customer:guestfield has to be set totrue.
Once a customer places the product in a cart, they can proceed with the checkout process.
The checkout service validates the data that come from customer's session token, the cart, and tiered prices, and then proceeds with the delivery and payment details. Then, it handles the payment and creates an order in the system, closing the cart.
You can trigger a checkout process through API as well by sending a request to the Triggering a checkout endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/checkout/{tenant}/checkouts/order' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'saas-token: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI2MTQ0MzU2MyIsImV4cCI6MTY5Nzk3MDUyOH0.F0b5jr6KeSoBCj-suTLuasmydaJEudc1ZrESkQXSCGk' \
-d '{
"cartId": "9b36757a-5ea1-4689-9ed3-fb630eb5048c",
"paymentMethods": [
{
"provider": "payment-gateway",
"customAttributes": {
"customer": "635544345",
"modeId": "9a33c7a5-9535-42af-a936-2fa6ece27579"
},
"method": "invoice"
}
],
"currency": "EUR",
"shipping": {
"methodId": "4-more_hours_timeframe",
"zoneId": "deliveryarea",
"methodName": "Delivery method name",
"amount": 10,
"shippingTaxCode": "STANDARD"
},
"deliveryWindowId": "cbda2a28-f0cc-11ed-a05b-0242ac120003",
"addresses": [
{
"contactName": "John Doe",
"companyName": "Emporix",
"street": "Fritz-Elsaas",
"streetNumber": "20",
"streetAppendix": "",
"zipCode": "70173",
"city": "Stuttgart",
"country": "DE",
"state": "",
"contactPhone": "123456789",
"type": "SHIPPING",
"metadata": {
"mixins": {}
},
"mixins": {}
},
{
"contactName": "John Doe",
"companyName": "Emporix",
"street": "Fritz-Elsaas",
"streetNumber": "20",
"streetAppendix": "",
"zipCode": "70173",
"city": "Stuttgart",
"country": "DE",
"state": "",
"contactPhone": "123456789",
"type": "BILLING",
"metadata": {
"mixins": {}
},
"mixins": {}
}
],
"customer": {
"id": "8765472",
"title": "MR",
"firstName": "John",
"middleName": "",
"lastName": "Doe",
"contactPhone": "56432245",
"email": "[email protected]",
"company": "Emporix",
"metadata": {
"mixins": {}
},
"mixins": {}
}
}'Last updated
Was this helpful?