> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-documentation/api-guides/orders/order/order.md). # 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. ## Order statuses The Order Service supports the following status values: These statuses are aligned with the Management Dashboard Orders guide. | Status | Description | Set By | When Used | | ------------- | --------------------------------------- | ----------------- | ------------------------------------------------------------- | | `CREATED` | New order that has been placed | System/Customer | Initial state after order creation | | `IN_CHECKOUT` | Awaiting invoice payment | System | Payment flow is in progress and the order is not paid yet | | `CONFIRMED` | Paid order ready for fulfillment | System/Employee | Payment is confirmed and the order can be processed | | `SHIPPED` | Order has been dispatched | Employee/Merchant | Fulfillment is complete and the shipment was sent to customer | | `COMPLETED` | Order request is finalized and realized | System/Employee | Order lifecycle is finished successfully | | `DECLINED` | Order could not be realized or canceled | Customer/Employee | Order is canceled by customer or declined during processing | Possible status transitions: * `IN_CHECKOUT` -> `CREATED` * `IN_CHECKOUT` -> `DECLINED` * `CREATED` -> `CONFIRMED` * `CREATED` -> `DECLINED` * `CONFIRMED` -> `SHIPPED` * `CONFIRMED` -> `COMPLETED` * `CONFIRMED` -> `DECLINED` * `SHIPPED` -> `COMPLETED` {% hint style="info" %} The initial order status depends on the checkout flow. Standard checkout orders are typically created with `CREATED`, while invoice or payment flows can start in `IN_CHECKOUT`. To audit all status changes for an order, use the historical transitions endpoint described in [Check the status transitions](#check-the-status-transitions). {% endhint %} ### Add shipment data before changing status to `SHIPPED` To use the `CONFIRMED` -> `SHIPPED` transition, append shipment details to the order first by using [Updating an order](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-tenant-managed#put-order-v2-tenant-salesorders-orderid) or [Partially updating an order](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-tenant-managed#patch-order-v2-tenant-salesorders-orderid). {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/hdjKtYpA1ID5jLYia9Ye" %} [API Reference](/api-documentation/api-guides/orders/order/api-reference.md) {% endcontent-ref %} ```bash curl --location --request PATCH 'https://api.emporix.io/order-v2/{tenant}/salesorders/{orderId}?recalculate=false' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \ --data '{ "shipments": [ { "shippedDate": "2026-07-28T00:00:00.000Z", "carrier": "UPS", "trackingNumber": "123456", "expectDeliveryOn": "2026-07-30T00:00:00.000Z" } ] }' ``` ## Scopes Scopes necessary to work with orders are: | Scope | Description | Used By | | ------------------------------ | ----------------------------------------------- | ----------------- | | `order.order_post` | Create a new order as a customer | Customer | | `order.order_read` | Read an order | Merchant/Employee | | `order.order_read_le` | Read legal entity orders | Customer | | `order.order_update` | Update an order | Merchant/Employee | | `order.order_update_completed` | Update an order with a `COMPLETED` status | Merchant/Employee | | `order.order_create` | Create a new order as a merchant | Merchant/Employee | | `order.order_delete` | Delete an order | Merchant/Employee | | `order.history_view` | View order history when logged in as a customer | Customer | | `order.order_readascustomer` | Read an order as a customer | Customer | | `order.order_updateascustomer` | Update an order as a customer | Customer | | `order.order_read_by_vendor` | Read an order with an assigned vendor | Vendor | | `order.order_manage_by_vendor` | Manage an order with an assigned vendor | Vendor | ## 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. ### Get authorization To create an order, first get the credentials to log in as a customer on the storefront. {% stepper %} {% step %} #### Request a service access token Get the `access_token` by sending the request to the [Requesting a service access token](https://developer.emporix.io/api-references/api-guides/authentication/oauth-service/api-reference/service-access-token). ```bash 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}" }' ``` {% endstep %} {% step %} #### Request an anonymous token Retrieve the `anonymous_token` by sending a request to the [Requesting an anonymous token](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#get-customerlogin-auth-anonymous-login) endpoint. ```bash curl 'https://api.emporix.io/customerlogin/auth/anonymous/login?tenant={tenant}&client_id&{client_id}' ``` {% endstep %} {% step %} #### Log in as a customer Log in as the customer by sending an authorization request to the [Logging in a customer](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login) endpoint. ```bash curl 'https://api.emporix.io/customer/{tenant}/login' \ --request POST \ --header 'Authorization: Bearer {{ANONYMOUS_ACCESS_TOKEN}}' \ --header 'Content-Type: application/json' \ --data '{ "email": "customer@emporix.com", "password": "Qwurmdch673;'" }' ``` {% endstep %} {% endstepper %} {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/CwpN0JJlaofAWIFORUfe" %} [API Reference](/api-documentation/api-guides/authentication/oauth-service/api-reference.md) {% endcontent-ref %} {% content-ref url="/pages/goJs2tqKAOpS2eob16wf" %} [API Reference](/api-documentation/api-guides/companies-and-customers/customer-management/api-reference.md) {% endcontent-ref %} ### Create an order {% stepper %} {% step %} #### Create an order As a merchant acting on behalf of a customer, send the request to the [Creating a new order](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-tenant-managed#post-order-v2-tenant-salesorders) endpoint. ```bash curl --location 'https://api.emporix.io/order-v2/{tenant}/salesorders' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{OAUTH2_ACCESS_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": "j.dee@emporix.com", "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": {} } ``` {% endstep %} {% step %} #### 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](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-tenant-managed#get-order-v2-tenant-salesorders-orderid) endpoint. ```bash curl 'https://api.emporix.io/order-v2/{tenant}/salesorders/{orderId}' \ --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' ``` * As a logged in customer, you can display your orders history in the store. Use the [Retrieving a list of orders](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-customer-managed#get-order-v2-tenant-orders) to fetch your own orders. **Standard (customer token):** ```bash curl 'https://api.emporix.io/order-v2/{tenant}/orders' \ --header 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' ``` **Alternatively (access token from client credentials + saas-token):** ```bash curl 'https://api.emporix.io/order-v2/{tenant}/orders' \ --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \ --header 'saas-token: {{SAAS_TOKEN}}' ``` {% endstep %} {% step %} #### 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](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-tenant-managed#patch-order-v2-tenant-salesorders-orderid) endpoint. ```bash curl --location --request PATCH 'https://api.emporix.io/order-v2/{tenant}/salesorders/{orderId}?recalculate=false' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \ --data '{ "status": "SHIPPED" }' ``` * As a customer, you can only change the order status from `CREATED` to `DECLINED` if for any reason you need to cancel the order. To decline the order, send the request to the [Updating order status](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-customer-managed#post-order-v2-tenant-orders-orderid-transitions) endpoint. **Standard (customer access token):** ```bash curl -L --request POST \ 'https://api.emporix.io/order-v2/{tenant}/orders/{orderId}/transitions' \ --header 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' \ --header 'Content-Type: application/json' \ --data '{"status": "DECLINED"}' ``` **Alternatively (access token from client credentials + saas-token):** ```bash curl -L --request POST \ 'https://api.emporix.io/order-v2/{tenant}/orders/{orderId}/transitions' \ --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \ --header 'saas-token: {{SAAS_TOKEN}}' \ --header 'Content-Type: application/json' \ --data '{"status": "DECLINED"}' ``` {% endstep %} {% step %} #### Check the status transitions Order Service APIs provide tools for checking possible next statuses and reviewing status change history. * As a merchant, check which status transitions are currently available for an order by sending the request to the [Retrieving status transitions for an order](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-tenant-managed#get-order-v2-tenant-salesorders-orderid-transitions) endpoint. ```bash curl -L \ --url 'https://api.emporix.io/order-v2/{tenant}/salesorders/{orderId}/transitions' \ --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \ --header 'Accept: */*' ``` * As a merchant, audit the status change history by sending the request to the [Retrieving historical status transitions for a specific order](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-tenant-managed#get-order-v2-tenant-salesorders-orderid-historical-transitions) endpoint. ```bash curl -L \ --url 'https://api.emporix.io/order-v2/{tenant}/salesorders/{orderId}/historical-transitions' \ --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \ --header 'Accept: */*' ``` * As a logged in customer, you can fetch possible status transitions for your order. Use the [Retrieving status transitions for an order](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-customer-managed#get-order-v2-tenant-orders-orderid-transitions) endpoint. **Standard (customer access token):** ```bash curl -L 'https://api.emporix.io/order-v2/{tenant}/orders/{orderId}/transitions' \ --header 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' ``` **Alternatively (access token from client credentials + saas-token):** ```bash curl -L 'https://api.emporix.io/order-v2/{tenant}/orders/{orderId}/transitions' \ --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \ --header 'saas-token: {{SAAS_TOKEN}}' ``` {% endstep %} {% endstepper %} {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/hdjKtYpA1ID5jLYia9Ye" %} [API Reference](/api-documentation/api-guides/orders/order/api-reference.md) {% endcontent-ref %} ## Order splitting To enable order splitting, the Order Service works directly with the [Vendor Service](/api-documentation/api-guides/companies-and-customers/vendor-service/api-reference.md). When a customer completes checkout, a single order is created containing all the selected products. Each order entry includes vendor information, making it a standard order with additional vendor details. If you need to separate this combined order into vendor-specific suborders, send the request to the [Splitting Order](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-tenant-managed#post-order-v2-tenant-salesorders-orderid-split) endpoint. You can also use a Digital Process for the splitting mechanism, see the Order Splitting Digital Process template for reference: {% file src="/files/8ojb17o2LYyVrOLROVxk" %} {% hint style="info" %} * Only orders in the CREATED status can be split. * Orders that are already suborders or have been split before cannot be split again. * Orders with discounts cannot be split. {% endhint %} To support this functionality, the following order attributes are introduced: * `entries.product.vendor` - marks a product as vendor dependent * `orderType` - populated only for orders involved in the splitting process * `masterOrder` - the identifier of a master order, available on suborders created after splitting the master order * `splitInfo` - information based on what was the suborder created * `subOrders` - list of suborders that were created after splitting the master order {% hint style="info" %} To check the end to end story for order splitting, see the [Vendor Tutorial - Order Split](/api-documentation/api-guides/companies-and-customers/vendor-service/vendor.md#order-split-example) example. {% endhint %} ## Order calculation 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. ```mermaid --- config: layout: fixed theme: base look: classic themeVariables: background: transparent lineColor: "#9CBBE3" arrowheadColor: "#9CBBE3" edgeLabelBackground: "#FFC128" edgeLabelTextColor: "#4C5359" --- flowchart TB subgraph subGraph0["`**Storefront**`"] A["Customer"] end subgraph subGraph1["`**Emporix**`"] CS["Cart Service"] CHK["Checkout Service"] OS["Order Service"] WS["Webhook Service"] end subgraph subGraph2["`**Customer's System**`"] ERP["ERP"] end A -- "1.Add product to cart" --> CS A -- "2.Start checkout" --> CHK CHK -- "3.Fetch cart data" --> CS CHK -- "4.Create order" --> OS OS -- "5.Receive order.created event" --> WS WS -- "6.Replicate order to ERP" --> ERP A@{ shape: rounded} CS@{ shape: rounded} CHK@{ shape: rounded} OS@{ shape: rounded} WS@{ shape: rounded} ERP@{ shape: rounded} A:::Class_04 CS:::Class_04 CHK:::Class_04 OS:::Class_04 WS:::Class_04 ERP:::Class_04 subGraph1:::Class_03 subGraph0:::Class_01 subGraph2:::Class_02 classDef Class_02 stroke-width:1px, stroke-dasharray: 0, stroke:#DDE6EE, fill:#DDE6EE classDef Class_01 stroke-width:1px, stroke-dasharray: 0, stroke:#A1BDDC, fill:#A1BDDC classDef Class_03 stroke-width:1px, stroke-dasharray: 0, stroke:#3b73bb, fill:#3b73bb classDef Class_04 fill:#F2F6FA, stroke:#E86C07 style subGraph1 color:#FFFFFF style subGraph0 color:#FFFFFF ``` {% hint style="warning" %} You have to register your listener in the Emporix Webhook Service so that the listener pushes order information to your ERP system. {% endhint %} {% hint style="info" %} To learn how pricing is calculated at Emporix, see the [Cart Service Tutorials](/api-documentation/api-guides/checkout/cart/cart.md#how-is-price-calculated). {% endhint %} ### 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](https://developer.emporix.io/api-references/api-guides/orders/order/api-reference/orders-tenant-managed#post-order-v2-tenant-salesorders) 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. ```mermaid --- config: layout: fixed theme: base look: classic themeVariables: background: transparent lineColor: "#9CBBE3" arrowheadColor: "#9CBBE3" edgeLabelBackground: "#FFC128" edgeLabelTextColor: "#4C5359" --- flowchart subgraph subGraph0["`**Storefront**`"] A["Customer"] end subgraph subGraph1["`**Emporix**`"] CS["Cart Service"] CHK["Checkout Service"] OS["Order Service"] WS["Webhook Service"] end subgraph subGraph2["`**Customer's System**`"] BFF["Backend for Frontend (BFF)"] ERP["ERP"] end A -- "1.Add product to cart" --> BFF BFF -- "2.Calculate a price" --> ERP BFF -- "3.Add a product with an external price to a cart" --> CS A -- "4.Start checkout" --> CHK CHK -- "5.Fetch cart data" --> CS CHK -- "6.Create order" --> OS OS -- "7.Receive order.created event" --> WS WS -- "8.Replicate order" --> ERP A@{ shape: rounded} CS@{ shape: rounded} CHK@{ shape: rounded} OS@{ shape: rounded} WS@{ shape: rounded} BFF@{ shape: rounded} ERP@{ shape: rounded} A:::Class_04 CS:::Class_04 CHK:::Class_04 OS:::Class_04 WS:::Class_04 BFF:::Class_04 ERP:::Class_04 subGraph1:::Class_03 subGraph0:::Class_01 subGraph2:::Class_02 classDef Class_02 stroke-width:1px, stroke-dasharray: 0, stroke:#DDE6EE, fill:#DDE6EE classDef Class_01 stroke-width:1px, stroke-dasharray: 0, stroke:#A1BDDC, fill:#A1BDDC classDef Class_03 stroke-width:1px, stroke-dasharray: 0, stroke:#3b73bb, fill:#3b73bb classDef Class_04 fill:#F2F6FA, stroke:#E86C07 style subGraph1 color:#FFFFFF style subGraph0 color:#FFFFFF ``` {% hint style="warning" %} You have to register your listener in the Emporix Webhook Service so that the listener pushes order information to your ERP system. {% endhint %} {% hint style="info" %} For more information, see the [External Pricing](/ce/extensibility-and-integrations/extensibility-cases/external-pricing-and-products.md) guides. {% endhint %} ### 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](/api-documentation/api-guides/orders/order/api-reference.md). This allows for seamless integration between Emporix and the external ERP system while maintaining flexibility in how orders are processed. ```mermaid --- config: layout: fixed theme: base look: classic themeVariables: background: transparent lineColor: "#9CBBE3" arrowheadColor: "#9CBBE3" edgeLabelBackground: "#FFC128" edgeLabelTextColor: "#4C5359" --- flowchart subgraph subGraph0["`**Storefront**`"] A["Customer"] end subgraph subGraph1["`**Emporix**`"] CS["Cart Service"] OS["Order Service"] WS["Webhook Service"] end subgraph subGraph2["`**Customer's System**`"] BFF["Backend for Frontend (BFF)"] ERP["ERP"] end A -- "1.Start checkout" --> BFF BFF -- "2.Get cart data" --> CS BFF -- "3.Simulate order" --> ERP BFF -- "4.Create sales order" --> OS OS -- "5.Receive order.created event" --> WS WS -- "6.Replicate order" --> ERP A@{ shape: rounded} CS@{ shape: rounded} OS@{ shape: rounded} WS@{ shape: rounded} BFF@{ shape: rounded} ERP@{ shape: rounded} A:::Class_04 CS:::Class_04 OS:::Class_04 WS:::Class_04 BFF:::Class_04 ERP:::Class_04 subGraph1:::Class_03 subGraph0:::Class_01 subGraph2:::Class_02 classDef Class_02 stroke-width:1px, stroke-dasharray: 0, stroke:#DDE6EE, fill:#DDE6EE classDef Class_01 stroke-width:1px, stroke-dasharray: 0, stroke:#A1BDDC, fill:#A1BDDC classDef Class_03 stroke-width:1px, stroke-dasharray: 0, stroke:#3b73bb, fill:#3b73bb classDef Class_04 fill:#F2F6FA, stroke:#E86C07 style subGraph1 color:#FFFFFF style subGraph0 color:#FFFFFF ``` {% hint style="warning" %} You have to register your listener in the Emporix Webhook Service so that the listener pushes order information to your ERP system. {% endhint %} ## 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 {% hint style="warning" %}
See the order calculation payload example ```json { "id": "EON1200", "createdBy": "45620894", "status": "CREATED", "lastStatusChange": "2025-06-10T12:31:39.614Z", "created": "2025-06-10T12:31:39.614Z", "channel": { "name": "storefront", "source": "https://your-storefront.com/" }, "cartId": "68481e9e8bf22744fc578572", "entries": [ { "id": "0_SLI_mobile-phone-s24-gross", "itemYrn": "urn:yaas:saasag:caasproduct:product:b2b2cstage;mobile-phone-s24-gross", "keepAsSeparateLineItem": true, "type": "INTERNAL", "amount": 2, "orderedAmount": 2, "effectiveQuantity": 2.0, "calculatedUnitPrice": { "netValue": 294.118, "grossValue": 350.0, "taxValue": 55.882, "taxCode": "STANDARD", "taxRate": 19.0 }, "product": { "id": "mobile-phone-s24-gross", "sku": "Mobile Phone s24 gross", "name": "Mobile Phone s24 gross", "localizedName": { "en": "Mobile Phone s24 gross" }, "published": true, "images": [ { "id": "67169928ceaab717e17f3734", "url": "http://res.cloudinary.com/saas-ag/image/upload/v1729534248/b2b2cstage/media/67169928ceaab717e17f3734", "stored": false } ], "productType": "BASIC" }, "price": { "priceId": "679ca63dbcdefe5b380c98bc", "priceListId": "abc123", "currency": "EUR", "originalAmount": 350.0, "effectiveAmount": 350.0, "basePrice": {}, "presentationPrice": {}, "metadata": { "createdAt": "2025-01-31T10:30:21.998Z", "modifiedAt": "2025-01-31T10:30:21.998Z", "version": 1 } }, "calculatedPrice": { "price": { "netValue": 588.235, "grossValue": 700.0, "taxValue": 111.765, "taxCode": "STANDARD", "taxRate": 19.0 }, "discountedPrice": { "netValue": 282.862, "grossValue": 336.606, "taxValue": 53.744, "taxCode": "STANDARD", "taxRate": 19.0, "appliedDiscounts": [ { "value": 83.394, "price": { "netValue": 70.079, "grossValue": 83.394, "taxValue": 13.315, "taxCode": "STANDARD", "taxRate": 19.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" }, { "id": "buy-2-get-1-free", "value": 280.0, "price": { "netValue": 235.294, "grossValue": 280.0, "taxValue": 44.706, "taxCode": "STANDARD", "taxRate": 19.0 }, "discountType": "PERCENT", "origin": "EXTERNAL" } ] }, "fees": [ { "id": "677d49ca3a421b451eab23f2", "type": "ABSOLUTE", "origin": "INTERNAL", "name": { "de": "Apple Picking Fee", "en": "Apple Picking Fee" }, "price": { "netValue": 3.5, "grossValue": 3.745, "taxValue": 0.245, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountedPrice": { "netValue": 3.083, "grossValue": 3.299, "taxValue": 0.216, "taxCode": "REDUCED", "taxRate": 7.0, "appliedDiscounts": [ { "value": 0.446, "price": { "netValue": 0.417, "grossValue": 0.446, "taxValue": 0.029, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] } } ], "totalFee": { "netValue": 3.083, "grossValue": 3.299, "taxValue": 0.216, "taxCode": "REDUCED", "taxRate": 7.0, "appliedDiscounts": [ { "value": 0.446, "price": { "netValue": 0.417, "grossValue": 0.446, "taxValue": 0.029, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] }, "totalDiscount": { "calculationType": "ApplyDiscountAfterTax", "value": 363.84, "price": { "netValue": 305.79, "grossValue": 363.84, "taxValue": 58.05 }, "appliedDiscounts": [ { "value": 83.84, "price": { "netValue": 70.496, "grossValue": 83.84, "taxValue": 13.344 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" }, { "id": "buy-2-get-1-free", "value": 280.0, "price": { "netValue": 235.294, "grossValue": 280.0, "taxValue": 44.706, "taxCode": "STANDARD", "taxRate": 19.0 }, "discountType": "PERCENT", "origin": "EXTERNAL" } ] }, "finalPrice": { "netValue": 285.945, "grossValue": 339.905, "taxValue": 53.96 } }, "priceMatchDetails": { "netValue": 294.11764705882354, "grossValue": 350.0, "taxValue": 55.88235294117647, "taxCode": "STANDARD", "taxRate": 19, "taxCountry": "DE" }, "externalDiscounts": [ { "id": "buy-2-get-1-free", "discountType": "PERCENT", "value": 40.0, "sequence": 1 } ] }, { "id": "shirt--301722c1-23e8-42b4-a4d8-1a5480fe3ea5", "itemYrn": "urn:yaas:saasag:caasproduct:product:b2b2cstage;shirt--301722c1-23e8-42b4-a4d8-1a5480fe3ea5", "keepAsSeparateLineItem": false, "type": "INTERNAL", "amount": 1, "orderedAmount": 1, "effectiveQuantity": 1.0, "calculatedUnitPrice": { "netValue": 9.346, "grossValue": 10.0, "taxValue": 0.654, "taxCode": "REDUCED", "taxRate": 7.0 }, "product": { "metadata": { "mixins": { "productTemplateAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/b2b2cstage/6818bfed8844a34a391a566e-templateAttributes_v1.json", "productVariantAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/b2b2cstage/6818bfed8844a34a391a566e-variantAttributes_v1.json" } }, "id": "shirt--301722c1-23e8-42b4-a4d8-1a5480fe3ea5", "sku": "shirt--red", "name": "shirt", "localizedName": { "en": "shirt" }, "description": "[de:, en:, pl:]", "published": true, "images": [], "mixins": { "productVariantAttributes": { "color": "red" } }, "productType": "VARIANT" }, "calculatedPrice": { "price": { "netValue": 9.346, "grossValue": 10.0, "taxValue": 0.654, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountedPrice": { "netValue": 8.233, "grossValue": 8.809, "taxValue": 0.576, "taxCode": "REDUCED", "taxRate": 7.0, "appliedDiscounts": [ { "value": 1.191, "price": { "netValue": 1.113, "grossValue": 1.191, "taxValue": 0.078, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] }, "totalDiscount": { "calculationType": "ApplyDiscountAfterTax", "value": 1.191, "price": { "netValue": 1.113, "grossValue": 1.191, "taxValue": 0.078, "taxCode": "REDUCED", "taxRate": 7.0 }, "appliedDiscounts": [ { "value": 1.191, "price": { "netValue": 1.113, "grossValue": 1.191, "taxValue": 0.078, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] }, "finalPrice": { "netValue": 8.233, "grossValue": 8.809, "taxValue": 0.576, "taxCode": "REDUCED", "taxRate": 7.0 } }, "priceMatchDetails": { "netValue": 9.345794392523365, "grossValue": 10.0, "taxValue": 0.6542056074766355, "taxCode": "REDUCED", "taxRate": 7, "taxCountry": "DE" } }, { "id": "2_SLI_mobile-phone-s27-gross", "itemYrn": "urn:yaas:saasag:caasproduct:product:b2b2cstage;mobile-phone-s27-gross", "keepAsSeparateLineItem": true, "type": "INTERNAL", "amount": 2, "orderedAmount": 2, "effectiveQuantity": 2.0, "calculatedUnitPrice": { "netValue": 51.402, "grossValue": 55.0, "taxValue": 3.598, "taxCode": "REDUCED", "taxRate": 7.0 }, "product": { "id": "mobile-phone-s27-gross", "sku": "mobile-phone-s27-gross", "name": "mobile-phone-s27-gross", "localizedName": { "en": "mobile-phone-s27-gross" }, "description": "[en:mobile-phone-s27-gross]", "published": true, "images": [], "productType": "BASIC" }, "calculatedPrice": { "price": { "netValue": 102.804, "grossValue": 110.0, "taxValue": 7.196, "taxCode": "REDUCED", "taxRate": 7.0 }, "upliftValue": { "netValue": 30.841, "grossValue": 33.0, "taxValue": 2.159, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountedPrice": { "netValue": 90.556, "grossValue": 96.895, "taxValue": 6.339, "taxCode": "REDUCED", "taxRate": 7.0, "appliedDiscounts": [ { "value": 13.105, "price": { "netValue": 12.248, "grossValue": 13.105, "taxValue": 0.857, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] }, "fees": [ { "id": "677d49ca3a421b451eab23f2", "type": "ABSOLUTE", "origin": "INTERNAL", "name": "Apple Picking Fee", "price": { "netValue": 3.5, "grossValue": 3.745, "taxValue": 0.245, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountedPrice": { "netValue": 3.083, "grossValue": 3.299, "taxValue": 0.216, "taxCode": "REDUCED", "taxRate": 7.0, "appliedDiscounts": [ { "value": 0.446, "price": { "netValue": 0.417, "grossValue": 0.446, "taxValue": 0.029, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] } } ], "totalFee": { "netValue": 3.083, "grossValue": 3.299, "taxValue": 0.216, "taxCode": "REDUCED", "taxRate": 7.0, "appliedDiscounts": [ { "value": 0.446, "price": { "netValue": 0.417, "grossValue": 0.446, "taxValue": 0.029, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] }, "totalDiscount": { "calculationType": "ApplyDiscountAfterTax", "value": 13.551, "price": { "netValue": 12.665, "grossValue": 13.551, "taxValue": 0.886, "taxCode": "REDUCED", "taxRate": 7.0 }, "appliedDiscounts": [ { "value": 13.551, "price": { "netValue": 12.665, "grossValue": 13.551, "taxValue": 0.886, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] }, "finalPrice": { "netValue": 93.639, "grossValue": 100.194, "taxValue": 6.555, "taxCode": "REDUCED", "taxRate": 7.0 } }, "priceMatchDetails": { "netValue": 51.401869158878505, "grossValue": 55.0, "taxValue": 3.5981308411214954, "taxCode": "REDUCED", "taxRate": 7, "taxCountry": "DE" } } ], "discounts": [ { "code": "TOTAL", "amount": 100.0, "currency": "EUR", "sequenceId": 1, "categoryRestricted": false }, { "code": "LS100EUROTOTAL", "amount": 100.0, "currency": "EUR", "name": "LS100EUROTOTAL", "calculationType": "ApplyDiscountBeforeTax", "discountType": "ABSOLUTE", "discountCalculationType": "TOTAL", "categoryRestricted": false } ], "customer": { "id": "45620894", "name": "John Dutton", "firstName": "John", "lastName": "Dutton", "email": "cartb2c.emporix@yopmail.com" }, "siteCode": "GrossSite", "countryCode": "DE", "billingAddress": { "contactName": "Dom", "street": "Kochanowskiego", "streetNumber": "21", "streetAppendix": "", "zipCode": "44-122", "city": "Gliwice", "country": "DE", "state": "Slaskie", "contactPhone": "" }, "shippingAddress": { "contactName": "Dom", "street": "Kochanowskiego", "streetNumber": "21", "streetAppendix": "", "zipCode": "44-122", "city": "Gliwice", "country": "DE", "state": "Slaskie", "contactPhone": "" }, "payments": [ { "status": "PENDING", "method": "invoice", "paidAmount": 0, "currency": "EUR", "provider": "stripe" } ], "totalAuthorizedAmount": 534.829, "currency": "EUR", "metadata": { "mixins": { "payments": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/CAAS/fees_checkout-mashup.json", "generalAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/orderGeneralAttributesMixIn.v9.json" }, "version": 1 }, "mixins": { "payments": { "elements": [ { "paymentMethodYrn": "urn:yaas:hybris:payments:payment-method:b2b2cstage;invoice", "fees": { "elements": [ { "yrn": "urn:yaas:saasag:fee:fee:b2b2cstage;678f552a949c723de46bdb14", "name": { "de": "Payment fee", "en": "Payment fee" }, "taxCode": "REDUCED", "total": { "subTotal": 73.89, "totalTax": 0.0, "total": 73.89, "discount": 0.0 } } ], "total": { "subTotal": 0, "totalTax": 0, "total": 0, "discount": 0 } }, "total": { "subTotal": 73.89, "totalTax": 0.0, "total": 73.89, "discount": 0.0 } } ], "total": { "subTotal": 73.89, "totalTax": 0.0, "total": 73.89, "discount": 0.0 } }, "generalAttributes": { "extendedOrderStatus": "10", "customerFirstOrder": false, "orderNumber": "EON1200" } }, "calculatedPrice": { "price": { "netValue": 700.385, "grossValue": 820.0, "taxValue": 119.615 }, "upliftValue": { "netValue": 30.841, "grossValue": 33.0, "taxValue": 2.159, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountedPrice": { "netValue": 381.651, "grossValue": 442.31, "taxValue": 60.659, "appliedDiscounts": [ { "value": 97.69, "price": { "netValue": 83.44, "grossValue": 97.69, "taxValue": 14.25 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" }, { "id": "buy-2-get-1-free", "value": 280.0, "price": { "netValue": 235.294, "grossValue": 280.0, "taxValue": 44.706, "taxCode": "STANDARD", "taxRate": 19.0 }, "discountType": "PERCENT", "origin": "EXTERNAL" } ] }, "paymentFees": [ { "id": "678f552a949c723de46bdb14", "type": "PERCENT", "origin": "INTERNAL", "name": { "de": "Payment fee", "en": "Payment fee" }, "price": { "netValue": 39.663, "grossValue": 42.439, "taxValue": 2.776, "taxCode": "REDUCED", "taxRate": 7.0 } } ], "fees": { "netValue": 46.663, "grossValue": 49.929, "taxValue": 3.266, "taxCode": "REDUCED", "taxRate": 7.0 }, "totalFee": { "netValue": 45.829, "grossValue": 49.037, "taxValue": 3.208, "taxCode": "REDUCED", "taxRate": 7.0, "appliedDiscounts": [ { "value": 0.892, "price": { "netValue": 0.834, "grossValue": 0.892, "taxValue": 0.058, "taxCode": "REDUCED", "taxRate": 7.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] }, "shipping": { "netValue": 10.0, "grossValue": 11.9, "taxValue": 1.9, "taxCode": "STANDARD", "taxRate": 19.0 }, "totalShipping": { "netValue": 8.808, "grossValue": 10.482, "taxValue": 1.674, "taxCode": "STANDARD", "taxRate": 19.0, "appliedDiscounts": [ { "value": 1.418, "price": { "netValue": 1.192, "grossValue": 1.418, "taxValue": 0.226, "taxCode": "STANDARD", "taxRate": 19.0 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" } ] }, "totalDiscount": { "calculationType": "ApplyDiscountAfterTax", "value": 380.0, "price": { "netValue": 320.76, "grossValue": 380.0, "taxValue": 59.24 }, "appliedDiscounts": [ { "value": 100.0, "price": { "netValue": 85.466, "grossValue": 100.0, "taxValue": 14.534 }, "discountType": "ABSOLUTE", "origin": "INTERNAL" }, { "id": "buy-2-get-1-free", "value": 280.0, "price": { "netValue": 235.294, "grossValue": 280.0, "taxValue": 44.706, "taxCode": "STANDARD", "taxRate": 19.0 }, "discountType": "PERCENT", "origin": "EXTERNAL" } ] }, "finalPrice": { "netValue": 436.288, "grossValue": 501.829, "taxValue": 65.541, "taxAggregate": { "lines": [ { "netValue": 144.618, "grossValue": 154.741, "taxValue": 10.123, "taxCode": "REDUCED", "taxRate": 7.0 }, { "netValue": 291.67, "grossValue": 347.088, "taxValue": 55.418, "taxCode": "STANDARD", "taxRate": 19.0 } ] } } } } ```
{% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.emporix.io/api-documentation/api-guides/orders/order/order.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.