Building an order receiver service

The order receiver handles the order requests sent from Norce Commerce and handles the integration and processes when sending it into the ERP system.

For sales orders it is important that this happens as soon as possible after the checkout is done, so that the orders gets fulfilled according to the promise to the end customer.

To this end Norce Commerce has defined a straightforward, but different integration process from all others, where a service inside Norce Commerce calls out directly to the integration, posting an order request and expects an answer back.

If something does not work, Norce Commerce has a retry functionality that repeats the call for a time until it is handled by the support organisation.

Examples and other resources

Guides
- Shopping integrations
Norce Commerce Connect
- OrderRequest
- OrderResponse

Responsibilites of the Order receiver

When an order is created in Norce Commerce, it should be configured to call the order receiver, that performs the order integration into the ERP system. Norce Commerce will send an JSON- or XML-request that contains all information needed to create a normal order. (Although it is possible to lookup more information using Norce Commerce Query, for special cases)

Your order receiver maps and sometimes add its own client specific business logic before sending the order to the target system.

Common responsibilites for a receiver is:

Mapping the OrderRequest to a format the target understands
Routing the order to the correct target (if client has many)
Handling errors or problems in the integration
Log and notify client or hosting partner
Return correct status to Norce Commerce with the OrderResponse

Configurations

You can configure the order post in the Client settings page under the ERP integration header.

Order receiver config

The important settings for the order receiver configuration are:

Erp endpoint type (SOAP, REST(Legacy), REST or No Integration)
REST is recommended practice, No integration disables the order integration (use this for demo purposes) and REST (Legacy) is a older version only for backward compatibility, use REST instead.
Erp endpoint url
The address to the integrations endpoint.
Erp endpoint username and password
the username and password to access the endpoint, basic authentication.

When in production it is required to have an endpoint behind basic authentication and using https.

The OrderRequest message

The OrderRequest is a large and complex contract.

Here are some important fields:

Header/ApplicationKey (GUID) Application key represents an application configured in Norce. See under settings/application in the Admin UI. Check this value to route or handle different markets differently in the integration.
ClientOrderRef This is the id from the basket (or from a source system) and is unique in the order ledger. Use this to identify retries of the same order (preventing duplicates)
Payments/Payment/PaymentRef Every payment has an identifier from the PSP. This should be sent in to the ERP and can be used there for tracking and matching payments to orders.
Items/OrderItem/PartNo The partno identifies the product and should be recognized by the ERP (if its a standard product).
Items/OrderItem/UnitPrice, UnitVat and Quantity The order has no line amount, instead you get the unit information and need to calculate tota amounts yourself, if needed.
Many places.../AdditionalInfo/Value/Code and Value Customer specific fields that is added in the checkout process will turn up here. You find additionalinfo under Customer, Company, Order and OrderItem, see Customization below.

An example OrderRequest message


{
  "SellTo": {
    "Company": null,
    "Person": {
      "CustomerCode": "XXXXXXXXXXXXXXXX",
      "CompanyCode": null,
      "FirstName": "Magnus",
      "LastName": "Blombergsson",
      "JobTitle": null,
      "PrivatePhone": "070111111",
      "CellPhone": "070111111",
      "WorkPhone": null,
      "Email": "someone@hotmail",
      "Address": {
        "Type": null,
        "Line1": "Sell here",
        "Line2": null,
        "ZipCode": "11111",
        "City": "Stockholm",
        "Region": null,
        "Country": "SE",
        "CareOf": null
      },
      "AdditionalInfo": [],
      "IsActive": null
    }
  },
  "BillTo": {
    "Person": {
      "CustomerCode": "2000032",
      "CompanyCode": null,
      "FirstName": "Magnus",
      "LastName": "Blombergsson",
      "JobTitle": null,
      "PrivatePhone": "070111111",
      "CellPhone": "070111111",
      "WorkPhone": null,
      "Email": "someone@hotmail",
      "Address": {
        "Type": null,
        "Line1": "Bill here",
        "Line2": null,
        "ZipCode": "11111",
        "City": "Stockholm",
        "Region": null,
        "Country": "SE",
        "CareOf": null
      },
      "AdditionalInfo": [],
      "IsActive": null
    }
  },
  "ShipTo": {
    "Person": {
      "CustomerCode": "2000032",
      "CompanyCode": null,
      "FirstName": "Magnus",
      "LastName": "Blombergsson",
      "JobTitle": null,
      "PrivatePhone": "070111111",
      "CellPhone": "070111111",
      "WorkPhone": null,
      "Email": "someone@hotmail",
      "Address": {
        "Type": null,
        "Line1": "Deliver here",
        "Line2": null,
        "ZipCode": "11111",
        "City": "Stockholm",
        "Region": null,
        "Country": "SE",
        "CareOf": null
      },
      "AdditionalInfo": [],
      "IsActive": null
    }
  },
  "SalesContactCode": null,
  "DoHold": false,
  "ClientOrderRef": "5670588",
  "SubmitDate": "2017-02-23T08:56:59.424326+01:00",
  "CurrencyCode": "SEK",
  "ReferId": null,
  "Payments": [
    {
      "PaymentCode": 14221,
      "PaymentMethodCode": "Klarna",
      "PaymentRef": "XXXXXXXXXXXXXXXX",
      "Amount": 572.50,
      "CurrencyCode": "SEK",
      "AdditionalInfo": [
        {
          "Id": 3,
          "Code": "BuyerIp",
          "Value": "127.0.0.1"
        }
      ]
    }
  ],
  "Discounts": [],
  "ShippingAdvice": {
    "DeliveryMethodCode": "DHL",
    "DoSMSNotify": true,
    "PickupStore": {
      "Code": "XXX",
      "Name": "Hemköp Järfälla",
      "IsDropPoint": true
    },
    "IsFeeChargedOnce": true,
    "IsComplete": true,
    "ShipAdvisorOrderCode": null
  },
  "Items": {
    "OrderItem": [
      {
        "LineNo": 1,
        "ParentLineNo": null,
        "Type": "ErpStandard",
        "TypeGroup": "Physical",
        "PartNo": "ABC123",
        "ErpPartNo": "ABC123",
        "InternalProductId": "28928524",
        "Description": "Exempel på artikel: Färg med kulör",
        "Quantity": 1,
        "UnitOfMeasure": null,
        "UnitPrice": 458.00,
        "UnitPriceOriginal": 458.00,
        "Discount": 0.00,
        "UnitVat": 114.5000,
        "PriceListNo": 1,
        "VatRate": 25.00,
        "Comment": null,
        "AdditionalInfo": [
          {
            "Id": 65,
            "Code": "EAN",
            "Value": "XXXXXXXXXXXXXXXX"
          },
          {
            "Id": 66,
            "Code": "Sample",
            "Value": "false"
          },
          {
            "Id": 67,
            "Code": "NCS",
            "Value": "S 1050-R90B"
          },
          {
            "Id": 68,
            "Code": "SampleOfPartNo",
            "Value": null
          }
        ],
        "PriceLists": [
          {
            "PriceListName": "STANDARD",
            "QtyBreak": 1,
            "UnitPrice": 458.00,
            "IsStandardPriceList": true,
            "IsActive": true
          }
        ],
        "Promotions": []
      },
      {
        "LineNo": 2,
        "ParentLineNo": null,
        "Type": "ErpStandard",
        "TypeGroup": "Physical",
        "PartNo": "ABC124",
        "ErpPartNo": "ABC124",
        "InternalProductId": "28928525",
        "Description": "Exempel på artikel: Tillbehör",
        "Quantity": 1,
        "UnitOfMeasure": null,
        "UnitPrice": 458.00,
        "UnitPriceOriginal": 458.00,
        "Discount": 0.00,
        "UnitVat": 114.5000,
        "PriceListNo": 1,
        "VatRate": 25.00,
        "Comment": null,
        "AdditionalInfo": [
          {
            "Id": 65,
            "Code": "EAN",
            "Value": "XXXXXXXXXXXXXXXX"
          },
          {
            "Id": 66,
            "Code": "Sample",
            "Value": "false"
          },
          {
            "Id": 67,
            "Code": "NCS",
            "Value": null
          },
          {
            "Id": 68,
            "Code": "SampleOfPartNo",
            "Value": null
          }
        ],
        "PriceLists": [
          {
            "PriceListName": "STANDARD",
            "QtyBreak": 1,
            "UnitPrice": 458.00,
            "IsStandardPriceList": true,
            "IsActive": true
          }
        ],
        "Promotions": []
      },
      {
        "LineNo": 3,
        "ParentLineNo": null,
        "Type": "ErpStandard",
        "TypeGroup": "Physical",
        "PartNo": "ABC125",
        "ErpPartNo": "ABC125",
        "InternalProductId": "28928525",
        "Description": "Exempel på artikel: Tapetprov",
        "Quantity": 1,
        "UnitOfMeasure": null,
        "UnitPrice": 458.00,
        "UnitPriceOriginal": 458.00,
        "Discount": 0.00,
        "UnitVat": 114.5000,
        "PriceListNo": 1,
        "VatRate": 25.00,
        "Comment": null,
        "AdditionalInfo": [
          {
            "Id": 65,
            "Code": "EAN",
            "Value": "XXXXXXXXXXXXXXXX"
          },
          {
            "Id": 66,
            "Code": "Sample",
            "Value": "true"
          },
          {
            "Id": 67,
            "Code": "NCS",
            "Value": null
          },
          {
            "Id": 68,
            "Code": "SampleOfPartNo",
            "Value": "ABC130"
          }
        ],
        "PriceLists": [
          {
            "PriceListName": "STANDARD",
            "QtyBreak": 1,
            "UnitPrice": 458.00,
            "IsStandardPriceList": true,
            "IsActive": true
          }
        ],
        "Promotions": []
      },
      {
        "LineNo": 4,
        "ParentLineNo": null,
        "Type": "Extended",
        "TypeGroup": "Physical",
        "PartNo": "ABC130",
        "ErpPartNo": "ABC130",
        "InternalProductId": "28928525",
        "Description": "Exempel på artikel: Tapet (not in store, ordered from supplier)",
        "Quantity": 1,
        "UnitOfMeasure": null,
        "UnitPrice": 458.00,
        "UnitPriceOriginal": 458.00,
        "Discount": 0.00,
        "UnitVat": 114.5000,
        "PriceListNo": 1,
        "VatRate": 25.00,
        "Comment": null,
        "AdditionalInfo": [
          {
            "Id": 65,
            "Code": "EAN",
            "Value": "XXXXXXXXXXXXXXXX"
          },
          {
            "Id": 66,
            "Code": "Sample",
            "Value": "false"
          },
          {
            "Id": 67,
            "Code": "NCS",
            "Value": null
          },
          {
            "Id": 68,
            "Code": "SampleOfPartNo",
            "Value": null
          }
        ],
        "PriceLists": [
          {
            "PriceListName": "STANDARD",
            "QtyBreak": 1,
            "UnitPrice": 458.00,
            "IsStandardPriceList": true,
            "IsActive": true
          }
        ],
        "Promotions": []
      },
      {
        "LineNo": 5,
        "ParentLineNo": null,
        "Type": "Freight",
        "TypeGroup": "Fee",
        "PartNo": "ABC127",
        "ErpPartNo": "ABC127",
        "InternalProductId": "28928527",
        "Description": "Exempel på artikel: Freight",
        "Quantity": 1,
        "UnitOfMeasure": null,
        "UnitPrice": 100.00,
        "UnitPriceOriginal": 100.00,
        "Discount": 0.00,
        "UnitVat": 25.00,
        "PriceListNo": 1,
        "VatRate": 25.00,
        "Comment": null,
        "AdditionalInfo": [
          {
            "Id": 65,
            "Code": "EAN",
            "Value": null
          },
          {
            "Id": 66,
            "Code": "Sample",
            "Value": "false"
          },
          {
            "Id": 67,
            "Code": "NCS",
            "Value": null
          },
          {
            "Id": 68,
            "Code": "SampleOfPartNo",
            "Value": null
          }
        ],
        "PriceLists": [
          {
            "PriceListName": "STANDARD",
            "QtyBreak": 1,
            "UnitPrice": 100.00,
            "IsStandardPriceList": true,
            "IsActive": true
          }
        ],
        "Promotions": []
      }
    ]
  },
  "AdditionalInfo": [
    {
      "Value": {
        "Id": 69,
        "Code": "StoreCode",
        "Value": "Central"
      }
    }
  ],
  "Header": {
    "ApplicationKey": "00000000-0000-0000-0000-000000000000"
  },
  "OrderType": "Order"
}


<OrderRequest xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="Enferno.Services.StormConnect.Contracts.Order">
    <SellTo>
        <Company/>
        <Person>
            <CustomerCode>XXXXXXXXXXXXXXXX</CustomerCode>
            <CompanyCode i:nil="true"/>
            <FirstName>Magnus</FirstName>
            <LastName>Blombergsson</LastName>
            <JobTitle i:nil="true"/>
            <PrivatePhone>070111111</PrivatePhone>
            <CellPhone>070111111</CellPhone>
            <WorkPhone i:nil="true"/>
            <Email>someone@hotmail</Email>
            <SSN/>
            <Address>
                <Type i:nil="true"/>
                <Line1>Sell here</Line1>
                <Line2 i:nil="true"/>
                <Box/>
                <ZipCode>11111</ZipCode>
                <City>Stockholm</City>
                <Region i:nil="true"/>
                <Country>SE</Country>
                <CareOf i:nil="true"/>
            </Address>
            <AdditionalInfo/>
            <IsActive i:nil="true"/>
        </Person>
    </SellTo>
    <BillTo>
        <Company/>
        <Person>
            <CustomerCode>2000032</CustomerCode>
            <CompanyCode i:nil="true"/>
            <FirstName>Magnus</FirstName>
            <LastName>Blombergsson</LastName>
            <JobTitle i:nil="true"/>
            <PrivatePhone>070111111</PrivatePhone>
            <CellPhone>070111111</CellPhone>
            <WorkPhone i:nil="true"/>
            <Email>someone@hotmail</Email>
            <SSN/>
            <Address>
                <Type i:nil="true"/>
                <Line1>Bill here</Line1>
                <Line2 i:nil="true"/>
                <Box/>
                <ZipCode>11111</ZipCode>
                <City>Stockholm</City>
                <Region i:nil="true"/>
                <Country>SE</Country>
                <CareOf i:nil="true"/>
            </Address>
            <AdditionalInfo/>
            <IsActive i:nil="true"/>
        </Person>
    </BillTo>
    <ShipTo>
        <Company/>
        <Person>
            <CustomerCode>2000032</CustomerCode>
            <CompanyCode i:nil="true"/>
            <FirstName>Magnus</FirstName>
            <LastName>Blombergsson</LastName>
            <JobTitle i:nil="true"/>
            <PrivatePhone>070111111</PrivatePhone>
            <CellPhone>070111111</CellPhone>
            <WorkPhone i:nil="true"/>
            <Email>someone@hotmail</Email>
            <SSN/>
            <Address>
                <Type i:nil="true"/>
                <Line1>Deliver here</Line1>
                <Line2 i:nil="true"/>
                <Box/>
                <ZipCode>11111</ZipCode>
                <City>Stockholm</City>
                <Region i:nil="true"/>
                <Country>SE</Country>
                <CareOf i:nil="true"/>
            </Address>
            <AdditionalInfo/>
            <IsActive i:nil="true"/>
        </Person>
    </ShipTo>
    <SalesContactCode i:nil="true"/>
    <SalesContactDivision/>
    <DoHold>false</DoHold>
    <ClientOrderRef>5670588</ClientOrderRef>
    <ErpOrderNo/>
    <CustomerOrderRef/>
    <CustomerOrderComment/>
    <SubmitDate>2017-02-23T08:56:59.424326+01:00</SubmitDate>
    <CurrencyCode>SEK</CurrencyCode>
    <ReferId i:nil="true"/>
    <Payments>
        <Payment>
            <PaymentCode>14221</PaymentCode>
            <PaymentMethodCode>Klarna</PaymentMethodCode>
            <PaymentRef>XXXXXXXXXXXXXXXX</PaymentRef>
            <Amount>572.50</Amount>
            <CurrencyCode>SEK</CurrencyCode>
            <AdditionalInfo/>
        </Payment>
    </Payments>
    <Discounts/>
    <ShippingAdvice>
        <DeliveryMethodCode>DHL</DeliveryMethodCode>
        <DoSMSNotify>true</DoSMSNotify>
        <PickupStore>
            <Code>XXX</Code>
            <Name>Hemköp Järfälla</Name>
            <IsDropPoint>true</IsDropPoint>
            <Address/>
        </PickupStore>
        <IsFeeChargedOnce>true</IsFeeChargedOnce>
        <IsComplete>true</IsComplete>
        <ShipAdvisorOrderCode i:nil="true"/>
    </ShippingAdvice>
    <Items>
        <OrderItem>
            <LineNo>1</LineNo>
            <ParentLineNo i:nil="true"/>
            <Type>ErpStandard</Type>
            <TypeGroup>Physical</TypeGroup>
            <PartNo>ABC123</PartNo>
            <ErpPartNo>ABC123</ErpPartNo>
            <InternalProductId>28928524</InternalProductId>
            <Description>Exempel på artikel: Färg med kulör</Description>
            <Quantity>1</Quantity>
            <UnitOfMeasure i:nil="true"/>
            <UnitPrice>458.00</UnitPrice>
            <UnitPriceOriginal>458.00</UnitPriceOriginal>
            <Discount>0.00</Discount>
            <UnitVat>114.5000</UnitVat>
            <PriceListNo>1</PriceListNo>
            <VatRate>25.00</VatRate>
            <Comment i:nil="true"/>
            <PriceLists/>
            <Promotions/>
            <AdditionalInfo>
                <Value>
                    <Id>65</Id>
                    <Code>EAN</Code>
                    <Value>XXXXXXXXXXXXXXXX</Value>
                </Value>
                <Value>
                    <Id>66</Id>
                    <Code>Sample</Code>
                    <Value>false</Value>
                </Value>
                <Value>
                    <Id>67</Id>
                    <Code>NCS</Code>
                    <Value>S 1050-R90B</Value>
                </Value>
                <Value>
                    <Id>68</Id>
                    <Code>SampleOfPartNo</Code>
                    <Value i:nil="true"/>
                </Value>
            </AdditionalInfo>
        </OrderItem>
        <OrderItem>
            <LineNo>2</LineNo>
            <ParentLineNo i:nil="true"/>
            <Type>ErpStandard</Type>
            <TypeGroup>Physical</TypeGroup>
            <PartNo>ABC124</PartNo>
            <ErpPartNo>ABC124</ErpPartNo>
            <InternalProductId>28928525</InternalProductId>
            <Description>Exempel på artikel: Tillbehör</Description>
            <Quantity>1</Quantity>
            <UnitOfMeasure i:nil="true"/>
            <UnitPrice>458.00</UnitPrice>
            <UnitPriceOriginal>458.00</UnitPriceOriginal>
            <Discount>0.00</Discount>
            <UnitVat>114.5000</UnitVat>
            <PriceListNo>1</PriceListNo>
            <VatRate>25.00</VatRate>
            <Comment i:nil="true"/>
            <PriceLists/>
            <Promotions/>
            <AdditionalInfo>
                <Value>
                    <Id>65</Id>
                    <Code>EAN</Code>
                    <Value>XXXXXXXXXXXXXXXX</Value>
                </Value>
                <Value>
                    <Id>66</Id>
                    <Code>Sample</Code>
                    <Value>false</Value>
                </Value>
                <Value>
                    <Id>67</Id>
                    <Code>NCS</Code>
                    <Value i:nil="true"/>
                </Value>
                <Value>
                    <Id>68</Id>
                    <Code>SampleOfPartNo</Code>
                    <Value i:nil="true"/>
                </Value>
            </AdditionalInfo>
        </OrderItem>
        <OrderItem>
            <LineNo>3</LineNo>
            <ParentLineNo i:nil="true"/>
            <Type>ErpStandard</Type>
            <TypeGroup>Physical</TypeGroup>
            <PartNo>ABC125</PartNo>
            <ErpPartNo>ABC125</ErpPartNo>
            <InternalProductId>28928525</InternalProductId>
            <Description>Exempel på artikel: Tapetprov</Description>
            <Quantity>1</Quantity>
            <UnitOfMeasure i:nil="true"/>
            <UnitPrice>458.00</UnitPrice>
            <UnitPriceOriginal>458.00</UnitPriceOriginal>
            <Discount>0.00</Discount>
            <UnitVat>114.5000</UnitVat>
            <PriceListNo>1</PriceListNo>
            <VatRate>25.00</VatRate>
            <Comment i:nil="true"/>
            <PriceLists/>
            <Promotions/>
            <AdditionalInfo>
                <Value>
                    <Id>65</Id>
                    <Code>EAN</Code>
                    <Value>XXXXXXXXXXXXXXXX</Value>
                </Value>
                <Value>
                    <Id>66</Id>
                    <Code>Sample</Code>
                    <Value>true</Value>
                </Value>
                <Value>
                    <Id>67</Id>
                    <Code>NCS</Code>
                    <Value i:nil="true"/>
                </Value>
                <Value>
                    <Id>68</Id>
                    <Code>SampleOfPartNo</Code>
                    <Value>ABC130</Value>
                </Value>
            </AdditionalInfo>
        </OrderItem>
        <OrderItem>
            <LineNo>4</LineNo>
            <ParentLineNo i:nil="true"/>
            <Type>Extended</Type>
            <TypeGroup>Physical</TypeGroup>
            <PartNo>ABC130</PartNo>
            <ErpPartNo>ABC130</ErpPartNo>
            <InternalProductId>28928525</InternalProductId>
            <Description>Exempel på artikel: Tapet (not in store, ordered from supplier)</Description>
            <Quantity>1</Quantity>
            <UnitOfMeasure i:nil="true"/>
            <UnitPrice>458.00</UnitPrice>
            <UnitPriceOriginal>458.00</UnitPriceOriginal>
            <Discount>0.00</Discount>
            <UnitVat>114.5000</UnitVat>
            <PriceListNo>1</PriceListNo>
            <VatRate>25.00</VatRate>
            <Comment i:nil="true"/>
            <PriceLists/>
            <Promotions/>
            <AdditionalInfo>
                <Value>
                    <Id>65</Id>
                    <Code>EAN</Code>
                    <Value>XXXXXXXXXXXXXXXX</Value>
                </Value>
                <Value>
                    <Id>66</Id>
                    <Code>Sample</Code>
                    <Value>false</Value>
                </Value>
                <Value>
                    <Id>67</Id>
                    <Code>NCS</Code>
                    <Value i:nil="true"/>
                </Value>
                <Value>
                    <Id>68</Id>
                    <Code>SampleOfPartNo</Code>
                    <Value i:nil="true"/>
                </Value>
            </AdditionalInfo>
        </OrderItem>
        <OrderItem>
            <LineNo>5</LineNo>
            <ParentLineNo i:nil="true"/>
            <Type>Freight</Type>
            <TypeGroup>Fee</TypeGroup>
            <PartNo>ABC127</PartNo>
            <ErpPartNo>ABC127</ErpPartNo>
            <InternalProductId>28928527</InternalProductId>
            <Description>Exempel på artikel: Freight</Description>
            <Quantity>1</Quantity>
            <UnitOfMeasure i:nil="true"/>
            <UnitPrice>100.00</UnitPrice>
            <UnitPriceOriginal>100.00</UnitPriceOriginal>
            <Discount>0.00</Discount>
            <UnitVat>25.0000</UnitVat>
            <PriceListNo>1</PriceListNo>
            <VatRate>25.00</VatRate>
            <Comment i:nil="true"/>
            <PriceLists/>
            <Promotions/>
            <AdditionalInfo>
                <Value>
                    <Id>65</Id>
                    <Code>EAN</Code>
                    <Value i:nil="true"/>
                </Value>
                <Value>
                    <Id>66</Id>
                    <Code>Sample</Code>
                    <Value>false</Value>
                </Value>
                <Value>
                    <Id>67</Id>
                    <Code>NCS</Code>
                    <Value i:nil="true"/>
                </Value>
                <Value>
                    <Id>68</Id>
                    <Code>SampleOfPartNo</Code>
                    <Value i:nil="true"/>
                </Value>
            </AdditionalInfo>
        </OrderItem>
    </Items>
    <Fees/>
    <AdditionalInfo>
        <Value>
            <Id>69</Id>
            <Code>StoreCode</Code>
            <Value>Central</Value>
        </Value>
    </AdditionalInfo>
    <Header>
        <ApplicationKey>00000000-0000-0000-0000-000000000000</ApplicationKey>
    </Header>
    <OrderType>Order</OrderType>
</OrderRequest>

Read more about the OrderRequest in the Norce Commerce Connect API Reference.

Responses to Norce

If Norce Commerce receives anything but 200 (OK) and a well formed OrderResponse, Norce Commerce will try send the same request again every 10 minutes for six hours or until we receive the OK. After that it will fall into manual handling and checkup by Norce support.

Your different possible responses are:

**OK, without an ERP order number (Asynchronous process) This means that the order is being processed by the ERP system, but is not confirmed yet. Some ERP systems takes a longer time to be processed. This response sets the Order in Norce to Allocated, and requires a status update, using SendOrderStatus in Norce Commerce Connect, to confirm the order.
**OK, with an ERP order number (Synchronous process) This means the the order is received and Confirmed by the ERP system. The order number is returned here in the response.
Failed This means that the order is failing during the integration process. The error is logged and tracked on your side in the order receiver. The description you set on the response message is logged in Norce.
Another httpStatusCode, like Service Unavailable, BadRequest, InternalServerError, etc. and no content in the response. This triggers Norce Commerces retry functionality and described above.

An example OrderResponse message


{
  "StatusCode": "OK",
  "Description": "No error, order status is set to confirmed.",
  "HasErpOrderNo": true,
  "ErpOrderNo": "ErpNo_5670588"
}

{
  "StatusCode": "OK",
  "Description": "No error, order status is set to allocated.",
  "HasErpOrderNo": false,
  "ErpOrderNo": null
}

{
  "StatusCode": "Failed",
  "Description": "Managed Error, this message is logged in Norce Commerce, no retry.",
  "HasErpOrderNo": false,
  "ErpOrderNo": null
}


<OrderResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
               xmlns="Enferno.Services.StormConnect.Contracts.Order">
    <StatusCode>OK</StatusCode>
    <Description>No error, order status is set to confirmed.</Description>
    <HasErpOrderNo>true</HasErpOrderNo>
    <ErpOrderNo>ErpNo_5670588</ErpOrderNo>
</OrderResponse>

<OrderResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
               xmlns="Enferno.Services.StormConnect.Contracts.Order">
<StatusCode>OK</StatusCode>
<Description>No error, order status is set to allocated.</Description>
<HasErpOrderNo>false</HasErpOrderNo>
<ErpOrderNo/>
</OrderResponse>

<StatusCode>Failed</StatusCode>
<Description>Managed Error, this message is logged in Norce Commerce, no retry.</Description>
<HasErpOrderNo>false</HasErpOrderNo>
<ErpOrderNo/>
        </OrderResponse>

Read more about the OrderResponse in the Connect API Reference.

Customization

The checkout process can add information on the Basket (that is added to the OrderRequest) by using the configurable info types on the client. These are added to the OrderRequest as items under * AdditionalInfo* collections.

Configure info types in the Admin UI for

Customer and companies here

Baskets here and basket items here

Recommended practices

Check for duplicates

It is important that the integration is designed with retries in mind. This means that duplicate checks must be in place. If, for example, Norce Commerce sends an order and gets a timeout exception. 10 minuter later the order will be sent again. The integration must handle that duplicate check, using the web order number (ClientOrderRef) as key.

Handle errors in the reciever

The only reason that the retry functionality in Norce Commerce should be used is when the receiver endpoint is down, configured incorrectly or during a service window. Design the receiver so that it logs and monitors errors directly and return a Failed status. Otherwise Norce Commerce will handle the problem much later, at the earliest six hours after the order was created and by people with no access to your receiver logs.

Use the retry functionality for service down time

The retry functionality exists to handle planned and expected service down times, both for the receiver and for the target system. When the receiver is down this works automatically, but use this also when the target system (ERP system) you pass on the order to is down. Return a status code, like ServiceUnavailable, until its up again and log the errors as warnings.