# Shopping Integrations This page describes how to design and implement shopping integrations between Norce Commerce and external systems, such as ERP and payment providers. It covers recommended integration patterns, API usage, and best practices for handling orders, deliveries, invoices, and related events. ## Order Integration Overview Order integration begins when the checkout process is completed and payment is committed with the Payment Service Provider (PSP). Norce Commerce offers a flexible integration solution that can be adapted to various business processes. However, starting from a default integration pattern simplifies discussions and implementation. **Order Integration Process Diagram:** The following diagram illustrates the typical order integration flow between Norce Commerce, ERP, and other systems. ![Order integration process](/assets/shoppingintegration-1.b247b246b926e2807abd4df2fa5ff5fa3165b269c1a1963d5249998eca30715f.003e135d.png) *Diagram: Order integration process between Norce Commerce and ERP systems.* ### Default Order Integration Pattern 1. **Order Reception in Norce Commerce** - When an order is received, Norce triggers the `OrderReceivedEvent`. - Integrations can listen to this event, fetch order data via Norce Commerce Query, and send notifications (e.g., email) to the end customer. - Norce pushes the actual order (`OrderRequest` message) to the integration using a REST protocol. An “OK” response is expected. If the call fails, Norce retries before alerting and logging the order. 2. **ERP Order Processing** - The ERP system receives the order asynchronously. It is best practice to store the message in a queue and return an “OK” to Norce immediately. - The ERP processes the order, which may take time. 3. **Order Status Updates** - The ERP can send status updates to Norce during processing. - An acknowledgement updates the order status in Norce Commerce to “Confirmed” and adds the ERP order number for traceability. - Other statuses, such as “canceled,” can also be sent. 4. **Order Dispatch and Delivery** - When the order is picked, packed, and shipped, the ERP sends a delivery note to Norce, including tracking information. - The integration can also notify the end customer via email. 5. **Invoice Creation and Payment Capture** - When the ERP creates an invoice, it sends the finalized order information to Norce. - Norce uses this invoice to trigger a capture message to the PSP. ### Order History and Traceability After the order is sent to the ERP, Norce Commerce does not track detailed order changes. Only general status changes are maintained. For clients needing detailed order history, it is best practice to provide this data directly from the ERP to the frontend application. ## Norce Commerce APIs for Integration Norce Commerce provides several APIs for system integration: - **Norce Commerce Connect:** Used for all system integrations. [Read how to call Norce Commerce Connect.](/developer-portal/system-integration/calling-norce-commerce-connect) - **Norce Commerce Query:** Used to look up and fetch data. [Read how to use Norce Commerce Query.](/developer-portal/system-integration/calling-norce-commerce-query) - **Norce Commerce Event:** Used to start processes when events occur in Norce Commerce. [Read how to use Norce Commerce Event.](/developer-portal/system-integration/using-norceevent) ## Integration Use Cases This section lists common integration endpoints, with explanations and links to examples and resources. For more detailed integration patterns, see [System integration patterns](/developer-portal/system-integration/system-integration-patterns). For order receiver implementation, see [Implement an Order Receiver Service](/developer-portal/system-integration/implement-an-order-receiver-service). ### Creating a Customer Order Norce Commerce sends a `CreateOrder` call (SOAP or REST) to a configured client URL and expects a status response or exception. - [Order creation process details](/developer-portal/system-integration/implement-an-order-receiver-service) - [OrderRequest schema](/api-reference/schemas/connectorder#orderrequest) - [OrderResponse schema](/api-reference/schemas/connectorder#orderresponse) - [ERP integration settings](https://norce-open-demo.admin-se.playground.norce.tech/settings/client/setting) ### Order Acknowledgement and Status Updates The ERP sends order acknowledgements and status updates to Norce Commerce using the [SendOrderStatus](/api-reference/connect/orderservice/openapi/order/sendorderstatus) endpoint. **Common statuses:** | Status | Description | | --- | --- | | Allocation | Waiting on response from ERP (initially set by Norce) | | Confirmed | Order confirmed by ERP; ERP order number sent to Norce | | BackOrder | Order pending, waiting on suppliers | | Delivered | Order delivered, not invoiced | | Invoiced | Order invoiced and completed | | Cancelled | Order annulled | | PartlyDelivered | Order partly delivered, not invoiced | | ReadyForPickup | Order ready for pickup at store | > Additional fields (order info types) can be included in the status update for Norce Commerce to store important order information. ### Creating Delivery Notes When a dispatch advice is created in the ERP, a delivery note can be sent to Norce Commerce with tracking information and references to the sales order. This step is optional but useful for customer notifications and tracking. - [CreateDeliveryNote API reference](/api-reference/connect/orderservice/openapi/order/createdeliverynote) - Delivery notes automatically update order status to “Delivered.” - Multiple delivery notes per order are allowed. - Parcel numbers can be included for customer display. [Postman delivery note example](https://documenter.getpostman.com/view/2973406/2sA35MzJve#27bfa8de-5c7d-4a81-a64b-0ec1c97eb3df) ### Creating Invoices and Capturing Payments For orders requiring payment capture, the ERP sends an invoice to Norce Commerce, which triggers payment capture with the PSP. - [CreateInvoice API reference](/api-reference/connect/orderservice/openapi/invoice/createinvoice) - Invoices automatically update order status to “Invoiced.” - Multiple invoices per order are allowed. > Payment functionality may vary by payment method and provider. Consult payment service documentation for details. [Postman invoice example](https://documenter.getpostman.com/view/2973406/2sA35MzJve#7f8c19f3-f316-49b1-b6e3-d42b4bda27ce) ### Credit Payments For order returns requiring repayment to the customer, use the [CreditPayment](/api-reference/connect/orderservice/openapi/invoice/creditpayment) endpoint. This requires a credit invoice for the sales order. Norce checks payment information and sends a credit payment call to the PSP. [Postman credit payment example](https://documenter.getpostman.com/view/2973406/2sA35MzJve#3ddb1d94-ee8f-4ba0-9c61-fff55566b6a6) ## Order Process Event Types Norce Commerce Event provides several event types for integration, mainly for notifications to customers or other systems. ### OrderReceivedEvent Triggered when Norce Commerce receives an order from the application, before sending it to the ERP. Delivered once per order. Use this event to send order received notifications. - [Administering Event types](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/skuchangednotification/detail) - [Quotations API reference](/api-reference/query/queryorders/openapi/orders/quotations) > **Note:** The order may not be fully created when this event is triggered. Send only minimal notifications at this stage. ### OrderConfirmedEvent Triggered when Norce Commerce receives an order confirmation from the ERP. Delivered once per order. Use this event to send confirmation emails. - [Administering Event types](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/skuchangednotification/detail) - [Orders API reference](/api-reference/query/queryorders/openapi/orders/orders) ### OrderReadyForPickupEvent Triggered when Norce Commerce receives an order status update indicating readiness for pickup. Delivered once per order. Use this event to send pickup notifications. - [Administering Event types](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/skuchangednotification/detail) - [Orders API reference](/api-reference/query/queryorders/openapi/orders/orders) ## Further Reading and Resources - [Implement an order receiver service](/developer-portal/system-integration/implement-an-order-receiver-service) - Code examples: [Jobs](/developer-portal/system-integration/job-check-examples), [Customer](/developer-portal/system-integration/customer-integration-examples) - [Postman integration examples](https://documenter.getpostman.com/view/2973406/2sA35MzJve) - [System integration patterns](/developer-portal/system-integration/system-integration-patterns) - [Calling Norce Commerce Connect](/developer-portal/system-integration/calling-norce-commerce-connect) - [Calling Norce Commerce Query](/developer-portal/system-integration/calling-norce-commerce-query) - [Using Norce Commerce Event](/developer-portal/system-integration/using-norceevent)