Order Tutorial
The Order Service is divided into two categories based on who manages the orders:
Tenant-Managed Orders – This refers to the management of customer orders. Customers create the orders, which are then accessible to your employees for processing, status updates, and data modifications.
Customer-Managed Orders – These are orders submitted by your customers. When logged into their account, customers can view and access their order history.
As Emporix offers full commerce functionality, order calculations and management can be handled end-to-end by our Commerce Orchestration Platform services. However, to support integrations with other systems, we have also introduced other capabilities. Order management with external systems can be approached using three different models:
asynchronous calculation
synchronous calculation
ERP calculated orders
Asynchronous calculation
Emporix utilizes an asynchronous pricing model, where all price calculations are dynamically determined at the cart/checkout stage. Product prices are initially replicated from an ERP system and stored in the Emporix, ensuring consistency across the platform.
During checkout, the final price is calculated based on customer-specific details, such as shipping address or payment methods. Prices are categorized into net or gross price models, depending on the price type, with customer assignments managed at the ship-to level:
Pricing rules (net or gross) are assigned based on the shipping address of the customer.
Different locations may have different tax regulations, so the system determines which price model applies based on where the order is being shipped.
Once an order is placed, the order information simply reflects the calculated prices without further modifications, ensuring accuracy and transparency in the final transaction.
You have to register your listener in the Emporix Webhook Service so that the listener pushes order information to your ERP system.
Synchronous calculation
In this approach, the Emporix cart interacts with an ERP system to retrieve real-time order calculations. Instead of using the Emporix calculation, the checkout uses the calculation provided by the ERP.
Commerce Orchestration Platform (COP) enables this functionality with external pricing, ensuring real-time accuracy.
Communication with the ERP system occurs using the BFF (Backend-for-Frontend) layer and with a POST request the order is send to an ERP system. This architecture ensures a secure, real-time pricing model while leveraging external systems for order calculations.
You have to register your listener in the Emporix Webhook Service so that the listener pushes order information to your ERP system.
ERP calculated order
With this use case, the Commerce Orchestration Platform cart is used to collect products and customer details, such as addresses. However, instead of using COP for final price calculations at checkout, the BFF (Backend-for-Frontend) layer communicates with the ERP to simulate the order, ensuring that all pricing, discounts, and rules from the ERP are applied before order creation.
Once the order is validated and priced by the ERP, the BFF layer creates the order in COP using the Sales Order API. This allows for seamless integration between Emporix and the external ERP system while maintaining flexibility in how orders are processed.
You have to register your listener in the Emporix Webhook Service so that the listener pushes order information to your ERP system.
Order calculation approaches comparison
Aspect
Asynchronous Calculation (Emporix driven)
Synchronous Calculation (External pricing)
ERP Calculated Order
Cart Usage
Emporix cart handles product selection & pricing.
Emporix cart calls an external system for pricing.
Emporix cart is used to collect products & addresses.
Price Calculation
Calculated at checkout within Emporix COP based on customer details (address, shipping, payment, etc.).
Fetched dynamically from an external system when items are displayed or added to the cart.
Calculated at checkout by ERP simulating an order.
Checkout Process
Handled entirely within Emporix.
Checkout is using external pricing.
Checkout occurs in Emporix, but order is simulated with an ERP system first.
Order Processing
Order info reflects the calculated prices from checkout.
Order is processed entirely in the external system (not Emporix).
Order is created in Emporix via the Sales Order API after ERP calculation.
Data Flow
Prices are replicated from ERP and stored in Emporix for calculation at checkout.
BFF fetches prices from ERP dynamically during cart interactions.
BFF sends cart details to ERP at checkout, then creates an order in Emporix.
Where Pricing Happens
In Emporix COP during checkout.
In an external system during cart interactions.
In ERP during checkout calculation (before order creation in Emporix).
Security
Secure – prices stored in Emporix cannot be altered.
Secure – only BFF can fetch external prices, preventing tampering.
Secure – BFF ensures price integrity before order creation.
Use Case
Best for businesses that want Emporix to manage pricing and apply customer-specific rules at checkout.
Ideal when ERP must control pricing in real time, and checkout happens in an external system.
Suitable when ERP validation is needed before order creation, but checkout remains in Emporix.
Summary of differences
Asynchronous calculation - Emporix controls pricing (replicated from ERP), and calculation happens at checkout.
Synchronous calculation - Pricing is provided by an external system, for example an ERP in real time, and checkout/order processing happens with external prices.
ERP calculated order - Emporix cart is used, but ERP simulates pricing at checkout before the order is created in Emporix.
Payload example
How to create an order on behalf of a customer
The Order Service functionality allows your employees to act on behalf of a customer and create an order for them. This way, merchants can facilitate order process for your customers. See the steps of the order process flow.
Create an order as a merchant
Get authorization
To create an order, first get the credentials to log in as a customer on the storefront:
Get the
access_tokenby sending the request to the Requesting a service access token.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -L
--request POST
--url 'https://api.emporix.io/oauth/token'
--header 'Content-Type: application/json'
--data '{
"client_id": "{client_id}",
"client_secret": "{client_secret}",
"grant_type": "client_credentials",
"scope": "scope=order.order_read order.order_delete order.order_create order.order_update tenant={tenant}"
}'Retrieve the
anonymous_tokenby 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 'https://api.emporix.io/customerlogin/auth/anonymous/login?tenant={tenant}&client_id&{client_id}'Log in as the customer by sending an authorization request to the Requesting a customer token endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl 'https://api.emporix.io/customer/{tenant}/login'
--request POST
--header 'Authorization: Bearer {anonymous_access_token}'
--header 'Content-Type: application/json'
--data '{
"email": "[email protected]",
"password": "Qwurmdch673;'"
}'Create an order
As a merchant acting on behalf of a customer, send the request to the Creating a new order endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl --location 'https://api.emporix.io/order-v2/{tenant}/salesorders'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: {customer_token}'
--data-raw '{
"entries": [
{
"id": "5c336893a981210009900071",
"amount": 3,
"orderedAmount": 3,
"effectiveQuantity": 3,
"calculatedUnitPrice": {
"netValue": 294.118,
"grossValue": 350.0,
"taxValue": 55.882,
"taxCode": "STANDARD",
"taxRate": 19.0
},
"measurementUnit": {
"value": 1,
"unit": "H87"
},
"calculatedPrice": {
"price": {
"netValue": 882.354,
"grossValue": 1050.0,
"taxValue": 167.646,
"taxCode": "STANDARD",
"taxRate": 19.0
},
"finalPrice": {
"netValue": 882.354,
"grossValue": 1050.0,
"taxValue": 167.646
}
}
}
],
"discounts": [],
"customer": {
"id": "{{first_customer_id}}",
"name": "John Dee",
"title": "MRS",
"firstName": "John",
"lastName": "Dee",
"email": "[email protected]",
"metadata": {
"mixins": {
"generalAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/customerGeneralAttributesMixIn.v4.json",
"backofficeAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/accountBoMixIn.v3.json",
"payment": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/paymentMixIn.v3.json",
"marketing": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/accountMarketingMixIn.v4.json",
"administration": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/administrativeMixIn.v4.json",
"deliveryOptions": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/deliveryOptionsMixIn.v6.json"
}
}
},
"siteCode": "main",
"countryCode": "DE",
"billingAddress": {
"contactName": "John Dee",
"street": "Maximilianstrasse",
"streetNumber": "55",
"streetAppendix": "",
"zipCode": "70173",
"city": "Stuttgart-Mitte",
"country": "DE",
"metadata": {
"mixins": {
"customAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/addressMixIn.v4.json"
}
}
},
"shippingAddress": {
"contactName": "John Dee",
"street": "Maximilianstrasse",
"streetNumber": "55",
"streetAppendix": "",
"zipCode": "70173",
"city": "Stuttgart-Mitte",
"country": "DE",
"metadata": {
"mixins": {
"customAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/addressMixIn.v4.json"
}
}
},
"payments": [
{
"status": "PENDING",
"method": "cash-on-delivery",
"paidAmount": 0,
"currency": "EUR"
}
],
"calculatedPrice": {
"price": {
"netValue": 882.354,
"grossValue": 1050.00,
"taxValue": 167.646
},
"finalPrice": {
"netValue": 882.354,
"grossValue": 1050.00,
"taxValue": 167.646
}
},
"channel": {}
}
Confirm order creation
You can retrieve the order details as a merchant or as the customer.
As a merchant, if you want to confirm that the order has been created, send the request to the Retrieving a specific order by ID endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl 'https://api.emporix.io/order-v2/{tenant}/salesorders/{orderId}'As a logged in customer, you can display your orders history in the store. Use the Retrieving a list of orders to fetch your own orders.
To test the endpoint, open the API reference below or check the example of a curl request.
curl 'https://api.emporix.io/order-v2/{tenant}/orders' \
--header 'Saas-Token: 'Change the order status
As a merchant, when the order has been prepared and dispatched, change the order status to
SHIPPED. Send the request to the Partially updating an order endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl --location --request PATCH 'https://api.emporix.io/order-v2/{tenant}/salesorders/{order_id}?recalculate=false'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer {YOUR_OAUTH2_TOKEN}'
--data '{
"status": "SHIPPED"
}'As a customer, you can only change the order status from
CREATEDtoDECLINEDif for any reason you need to cancel the order. To decline the order, send the quest to the Updating order status endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -L \
--request POST \
--url 'https://api.emporix.io/order-v2/{tenant}/orders/{orderId}/transitions' \
--header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' \
--header 'saas-token: text' \
--header 'Content-Type: application/json' \
--data '{
"status": "DECLINED"
}'Check the status transitions
Order Service APIs provide also tools for controlling the status transitions logs.
As a merchant, check the status history of the order by sending the request to the Retrieving status transitions for an order endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -L
--url 'https://api.emporix.io/order-v2/{tenant}/salesorders/{orderId}/transitions'
--header 'Authorization: Bearer {YOUR_OAUTH2_TOKEN}'
--header 'Accept: */*'As a logged in customer, you can fetch your own order status transitions history. Use the Retrieving status transitions for an order endpoint.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -L \
--url 'https://api.emporix.io/order-v2/{tenant}/orders/{orderId}/transitions' \
--header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' \
--header 'saas-token: text' \
--header 'Accept: */*'Last updated
Was this helpful?