DocumentationSwaggerUser docsSystem status
Order

API Reference

Introduction to Omnium Orders

An order in Omnium could originate from any sales channel and operate and behave in different ways in. For instance, it could be an order placed from a web shop, a sale from POS, or a click&collect reservation. As a modern order management system, Omnium accepts all types of orders, and offers customizable workflows for all kinds.

In this section you’ll (hopefully) learn everything you need to know to get started importing, managing and reading orders using Omnium’s API.

Order properties

When working with the Order API, the same model is used for adding, updating and fetching orders.

Crucial properties

ID
The ID of the order must be unique. If you want Omnium to generate an order number, this is possible using the X API when adding orders. Customer ID: This is usually set to the customer’s phone number, email or ID from an external system. We accept everything, but try avoid 'special characters' such as '+' or '%'.

MarketId
The order must have a market ID which corresponds to a market added to Omnium. A market would typically be “Epic Enterprise Norway”, which would contain stores such as “Epic Enterprise Webshop” and “Epic Enterprise Store New York”. Markets are not entities that are added to Omnium, but settings that are configured.

StoreId
The order must also have a “StoreId” set which corresponds to a store in Omnium. The StoreId should represent the selling store. Unlike markets, stores are entities that are created or imported to Omnium.

OrderType
The OrderType must be set to a corresponding OrderType defined in the Omnium configuration, which will ensure the correct workflow is executed when the order is processed.

Status
The order status defines the current state of the order and should also match a status defined for the current OrderType. Typically, this would be set to "New" for orders that has yet been processed (not yet shipped for instance, and/or payment has not been captured).

Complete model
The full order model definition can be found in swagger.

OrderForm and LineItems(Order Lines)

Each order contains an order form. The order form contains lists of order lines, payments and shipments. LineItems is a list of order lines, each order line contains price(s), quantity, product data and various meta data.

Shipments

The order form contains one or multiple shipments. A shipment contains shipping information and order lines. An order will usually only contain a single shipment, but for partial deliveries or multiple senders or recipients, there will be multiple shipments. A shipment contains one or multiple order lines, and an order line cannot be added to multiple shipments. A shipment must also contain a "warehouseCode". This should be set to the ID of a store in Omnium that is the shipment sender.

Payments

For every order, there should be a payment corresponding to the total amount of the order. Most commonly, an order will be sent to Omnium after the order has been placed from an e-commerce site. That means that the payment should already be authenticated in the payment provider (such as Klarna, Paypal or Vipps). Omnium will then be able to void, capture or credit the payment later on in the order process. The required properties in order to get this right are the following:

PropertyTypeDescriptionInformation
PaymentMethodNamestringValue to indentify correct payment provider("Klarna" for instance)Required
TransactionIdstringUnique id for this payment(from payment provider)Required
TransactionTypestring"Authorization", "Captured", "Credit", "Invoiced", "ReleaseRemainingAuthorization" or "Invoiced"Required
Statusstring"Processed" when successful, and "Failed" on unsuccessfulRequired
AmountdecimalThe amount for this payment transactionRequired

Discount

There are a few ways to add discounts to an order:

  • Simple Discount: Set the discounted property on an order line. This allows you to set the discounted amount directly on the order line. Example: An order line containing two sweaters with an original price of $200, but with a 10% discount.

  • Advanced Discount: Set the list of discounts objects beneath orderForm. This allows you to add more advanced discounts to the order, such as order-level discounts, percentage-based discounts, or other types, like "3 for 2".

  • Shipment-Specific Discount: The model is identical to the advanced discount but should be added beneath the shipment. This is typically used for adding a "free shipping" discount to the shipment.

Reward Types

ValueType
0None
1Money
2Percentage
3Free
4FixedPrice
5Gift
6MultiBuys

Discount Types

ValueType
0None
1LineItem
2Order
3Shipping
4Manual
5BonusPoints

Examples

Simple: Discounted Order Line

"lineItems": [
  {
    "lineItemId": "1",
    "code": "0123ABC",
    "placedPrice": 200.0,
    "quantity": 1.0,
    "discounted": 20.0,
    "taxRate": 25
  }
]

Advanced: 20% Order-Level Discount

"orderForm": {
  "discounts": [
    {
      "discountType": "Order",
      "discountName": "Splendid discount! 60 percent discount!",
      "discountValue": 60,
      "rewardType": "Percentage"
    }
  ]
}

Advanced: $10 Order-Level Discount

"orderForm": {
  "discounts": [
    {
      "discountType": "Order",
      "discountName": "Ten bucks off!",
      "discountValue": 10,
      "rewardType": "Money"
    }
  ]
}

Advanced: Fixed Price Order Line Discount

All items involved in the fixed price promotion should be added to the list skuIds. The promotion calculator will prioritize items from highest to lowest price.

If the setting SplitMultibuyPromotionOrderLines is true, the order lines involved in the promotion will be split to have quantity = 1 per order line.

"orderForm": {
  "discounts": [
    {
      "discountType": "LineItem",
      "discountName": "4 items for 99.90",
      "rewardType": "FixedPrice",
      "skuIds": ["sku-1", "sku-2"],
      "promotionFixedPriceReward": {
        "fixedPriceQuantity": 4,
        "fixedPricePrice": 99.90
      }
    }
  ]
}

Advanced: 3 for 2 Order Line Discount

All items involved in the multi-buys promotion should be added to the list skuIds. By default, the promotion calculator will prioritize items from lowest to highest price. This can be changed with the setting SortMultibuyItemsDescending.

"orderForm": {
  "discounts": [
    {
      "discountType": "LineItem",
      "discountName": "3 for 2 bikes!",
      "rewardType": "MultiBuys",
      "skuIds": ["sku-1", "sku-2"],
      "promotionMultiBuyReward": {
        "requiredBuyAmount": 2,
        "numberOfDiscountedItems": 1,
        "percentage": 100
      }
    }
  ]
}

Advanced: Combination of Fixed Price and Percentage Order Line Discounts

Order the discounts from highest priority.

"orderForm": {
  "discounts": [
    {
      "discountType": "LineItem",
      "discountName": "4 items for 99.90",
      "rewardType": "FixedPrice",
      "skuIds": ["sku-1", "sku-2"],
      "promotionFixedPriceReward": {
        "fixedPriceQuantity": 4,
        "fixedPricePrice": 99.90
      }
    },
    {
      "discountType": "LineItem",
      "discountName": "Fifty percent discount!",
      "discountValue": 50,
      "rewardType": "Percentage",
      "skuIds": ["sku-1"]
    }
  ]
}

Shipping Discount

"orderForm": {
  "shipments": [
    {
      "discounts": [
        {
          "discountType": "Shipping",
          "discountName": "Free shipping 4 you!",
          "discountValue": 100,
          "rewardType": "Percentage"
        }
      ]
    }
  ]
}

Price properties

The order line consists of multiple price properties. Generally, only the PlacedPrice and TaxRate should be set, in order for the other price properties to be calculated correctly.

PlacedPrice The full price per item, without any discounts added. The PlacedPrice should not be multiplied by quantity.

DiscountedPrice

This price is calculated by the order calculator and should not be set manually.

The discounted price is the total price of the order line reduced by the order line level discounts applied. Any order level discounts are not applied to the discounted price.

The discounted price is calculated with the following formula:

DiscountedPrice = ( ( Quantity - CanceledQuantity ) * PlacedPrice ) - ( ( Discounted / Quantity ) * ( Quantity - CanceledQuantity ) )

ExtendedPrice

This price is calculated by the order calculator and should not be set manually.

The extended price is the total line item price with all discounts applied, including both order line level and order level discounts.

The extended price is calculated with the following formula:

ExtendedPrice = DiscountedPrice - ( ( DiscountedPrice / ( [ Sum of DiscountedPrice for all order lines ] ) * DiscountAmount )

SuggestedRetailPrice

This price is not used in any calculations, and will not be changed by Omnium.

The placed price could be a customer-specific price based on price agreements (e.g., 10% off suggested retail price). In these scenarios, the placed price would already contain a discount, and the suggested retail price could be used to indicate savings for the end customer by comparing suggested retail price to the discounted price.

The price could also be used for reports or statistics by third-party applications.

Price Example This is an example of how the prices would look after calculation when a 10% order discount is added to the order. The case is that the customer bought two products with an original price of $500, but with a 10% discount. So, the customer paid 2 x (500 - 10%) = 900.

{
    "lineItemId": "1",
    "quantity": 2,
    "placedPrice": 500,
    "placedPriceExclTax": 400,     // Calculated
    "discountedPrice": 1000,       // Calculated
    "discountedPriceExclTax": 800, // Calculated
    "discounted": 0,               // Discount was added as an order discount, not as a "basic" order line discount.
    "discountedExclTax": 0,
    "orderDiscountAmount": 100,    // Calculated
    "extendedPrice": 900,          // Calculated
    "extendedPriceExclTax": 720,   // Calculated
    "taxTotal": 180,               // Calculated
    "taxRate": 25,                 // Calculated
    ...
}

Order types

The order type is used for triggering different workflows. A point of sale order can have a different process than an online order.

The order type string is a free text string, but orders in Omnium should have a corresponding order type in the settings in order for workflows to run correctly.

Omnium has five predefined order types, commonly used:

Order typeDescription
PosOrder from Point of Sale system
OnlineOrder from B2B / B2C web portals
ClickAndCollectClick and collect orders (Not paid)
BopisBuy online, pick up in store (Paid)
PreOrderOrders placed for products that are not yet released

Adding orders

An order can be added to Omnium in numerous ways. It can be:

  • Imported via API
  • Created from a cart via API
  • Created from a cart via Omnium's UI
  • Created from Omnium's UI
  • Imported from Excel via Omnium's UI

Example: Creating an order

In order to meet multiple demands and be as flexible as Omnium is, Omnium’s order model is rather large and contains many fields. Most likely, you’ll not be in need of all of them. Below is a basic example of how to add an order, using the POST ​/api​/Orders API.

{
	"id": "EPIC000001",
	"customerId": "4793246662",
	"billingCurrency": "NOK",
	"customerName": "Ola Nordmann",
	"marketId": "epic_market_no",
	"storeId": "epic_webshop_no",
	"customerPhone": "4793246662",
	"customerEmail": "ola.nordmann@omnium.no",
	"status": "New",
	"billingAddress": {
		"daytimePhoneNumber": "4793246662",
		"name": "Ola Nordmann",
		"line1": "Lille Grensen 3",
		"city": "Oslo",
		"countryCode": "NO",
		"countryName": "Norge",
		"postalCode": "1415",
		"email": "ola.nordmann@omnium.no"
	},
	"orderForm": {
		"payments": [
			{
				"amount": 49.5,
				"paymentMethodName": "Klarna",
				"status": "Processed",
				"transactionId": "123456789",
				"transactionType": "Authorization"
			}
		],
		"shipments": [
			{
				"shipmentId": "1",
				"shippingMethodName": "PostNord",
				"warehouseCode": "epic_company_main_warehouse",
				"lineItems": [
					{
						"lineItemId": "1",
						"code": "0123ABC",
						"placedPrice": 99.0,
						"quantity": 1.0,
						"taxRate": 25
					}
				],
				"address": {
					"name": "Ola Nordmann",
					"line1": "Lille Grensen 3",
					"city": "Oslo",
					"countryName": "Norge",
					"countryCode": "NO",
					"postalCode": "0159",
					"email": "ola.nordmann@omnium.no"
				}
			}
		],
		"lineItems": [
			{
				"lineItemId": "1",
				"code": "0123ABC",
				"placedPrice": 99.0,
				"quantity": 1.0,
				"taxRate": 25
			}
		],
		"discounts": [
			{
				"discountType": "Order",
				"discountName": "Fifty percent discount!",
				"discountValue": 50,
				"rewardType": "Percentage"
			}
		]
	},
	"orderType": "Online"
}

Relevant swagger documentation

Fetching orders

There are multiple endpoints that could be used to retrieve an order, as there are various ways of searching for an order. This could be faceted free-text searching, filtered search by customer metadata or product data, or simply fetching a single order using the order ID.

Get a single order

Standard Online order

This is the data from the order created in the order creation example.

{
	"id": "ORDR000001",
	"orderNumber": "ORDR000001", // Enriched from ID
	"customerId": "4793246662",
	"customerNumber": "4793246662", // Enriched from customerId
	"billingCurrency": "NOK",
	"customerName": "Ola Nordmann",
	"customerPhone": "4793246662",
	"customerEmail": "ola.nordmann@omnium.no",
	"customerType": "B2C", // Enriched from market configuration
	"marketId": "NOR",
	"billingAddress": {
		"name": "Ola Nordmann",
		"line1": "Lille Grensen 3",
		"city": "Oslo",
		"countryCode": "NO",
		"countryName": "Norge",
		"postalCode": "1415",
		"daytimePhoneNumber": "4793246662",
		"eveningPhoneNumber": "",
		"email": "ola.nordmann@omnium.no"
	},
	"orderForm": {
		"shipments": [
			{
				"shipmentId": "1",
				"shippingMethodName": "PostNord",
				"shippingLabel": "PostNord", // Enriched from shipping provider
				"shippingTax": 0,
				"shippingDiscountAmount": 0,
				"shippingSubTotal": 0,
				"shippingTotal": 0,
				"shippingSubTotalExclTax": 0,
				"status": "AwaitingInventory", // Default status
				"orderStatus": "New", // Default status
				"subTotal": 49.5,
				"total": 49.5,
				"taxTotal": 9.9,
				"warehouseCode": "epic_company_main_warehouse",
				"lineItems": [
					{
						"lineItemId": "1",
						"code": "0123ABC",
						"displayName": "Omnium Super Stylish sweater /w logo", // Enriched from product
						"alternativeProductName": "Logo sweater", // Enriched from product
						"placedPrice": 99,
						"placedPriceExclTax": 79.2,
						"extendedPrice": 49.5, // Calculated total line amount
						"extendedPriceExclTax": 39.6,
						"discountedPrice": 99, // Calculated discounted amount, excluding order level discount
						"discountedPriceExclTax": 79.2,
						"suggestedRetailPrice": 0, // Optional values, used by 3rd party systems and reporting
						"suggestedRetailPriceExclTax": 0,
						"orderDiscountAmount": 49.5, // The order level discount amount
						"quantity": 1,
						"unit": "pcs", // Enriched from product
						"returnQuantity": 0,
						"canceledQuantity": 0,
						"deliveredQuantity": 0,
						"isGift": false,
						"isReadOnly": false, // Read only is only used in the Omnium UI
						"cost": 19, // the product/provide cost of the order line, per unit. Enriched from product
						"costTotal": 19,
						"discounted": 0, // The order line level discount
						"discountedExclTax": 0,
						"taxTotal": 9.9, // Calculated tax rate
						"taxRate": 25,
						"size": "M", // Enriched from product
						"color": "Black", // Enriched from product
						"brand": "Omnium Sweaters 'n Jeans", // Enriched from product
						"productId": "ABC-123_no", // Enriched from product
						"webSiteProductUrl": "https://omniumbikeshop.azurewebsites.net/product/0123abc?productName=", // Enriched from product
						"updateStock": false,
						"isPackage": false
					}
				],
				"address": {
					"name": "Ola Nordmann",
					"line1": "Lille Grensen 3",
					"city": "Oslo",
					"countryCode": "NO",
					"countryName": "Norge",
					"postalCode": "0159",
					"daytimePhoneNumber": "",
					"eveningPhoneNumber": "",
					"email": "ola.nordmann@omnium.no"
				},
				"transit": false,
				"expectedDeliveryDate": "0001-01-01T00:00:00"
			}
		],
		"lineItems": [
			{
				"lineItemId": "1",
				"code": "0123ABC",
				"displayName": "Omnium Super Stylish sweater /w logo", // Enriched from product
				"alternativeProductName": "Logo sweater", // Enriched from product
				"placedPrice": 99,
				"placedPriceExclTax": 79.2,
				"extendedPrice": 49.5, // Calculated total line amount
				"extendedPriceExclTax": 39.6,
				"discountedPrice": 99, // Calculated discounted amount, excluding order level discount
				"discountedPriceExclTax": 79.2,
				"suggestedRetailPrice": 0, // Optional values, used by 3rd party systems and reporting
				"suggestedRetailPriceExclTax": 0,
				"orderDiscountAmount": 49.5, // The order level discount amount
				"quantity": 1,
				"unit": "pcs", // Enriched from product
				"returnQuantity": 0,
				"canceledQuantity": 0,
				"deliveredQuantity": 0,
				"isGift": false,
				"isReadOnly": false, // Read only is only used in the Omnium UI
				"cost": 19, // the product/provide cost of the order line, per unit. Enriched from product
				"costTotal": 19,
				"discounted": 0, // The order line level discount
				"discountedExclTax": 0,
				"taxTotal": 9.9, // Calculated tax rate
				"taxRate": 25,
				"size": "M", // Enriched from product
				"color": "Black", // Enriched from product
				"brand": "Omnium Sweaters 'n Jeans", // Enriched from product
				"productId": "ABC-123_no", // Enriched from product
				"webSiteProductUrl": "https://omniumbikeshop.azurewebsites.net/product/0123abc?productName=", // Enriched from product
				"updateStock": false,
				"isPackage": false
			}
		],
		"discounts": [
			{
				"discountType": "Order",
				"discountAmount": 49.5,
				"discountName": "Fifty percent discount!",
				"discountValue": 50,
				"discountSource": "Manual", // Manual or Campaign
				"rewardType": "Percentage"
			}
		],
		"payments": [
			{
				"amount": 49.5,
				"paymentId": 0,
				"paymentMethodId": "00000000-0000-0000-0000-000000000000",
				"paymentMethodName": "Klarna",
				"status": "Processed",
				"transactionId": "123456789",
				"transactionType": "Authorization",
				"created": "2022-12-04T07:28:50.1521376Z",
				"isManuallyAdded": false
			}
		],
		"shippingDiscountTotal": 0,
		"shippingSubTotal": 0,
		"shippingSubTotalExclTax": 0,
		"shippingTotal": 0,
		"handlingTotal": 0,
		"orderLevelTax": 0,
		"taxTotal": 9.9,
		"discountAmount": 49.5,
		"subTotal": 49.5,
		"subTotalExclTax": 39.6,
		"total": 49.5,
		"totalExclTax": 39.6,
		"authorizedPaymentTotal": 0,
		"capturedPaymentTotal": 0,
		"fullRefund": false
	},
	"shippingDiscountTotal": 0,
	"shippingSubTotal": 0,
	"status": "New",
	"remainingPayment": 0,
	"modified": "2022-12-04T07:28:50.152347Z",
	"created": "2022-12-04T07:28:50.1523193Z",
	"orderType": "Online",
	"storeId": "epic_webshop_no",
	"lineItemsCost": 0,
	"netTotal": 49.5, // Calculated order form total minus return order form totals
	"netTotalExclTax": 39.6,
	"isReadOnly": false,
	"isNotificationsDisabled": false
}

Updating orders

There are multiple ways an order could be update, and multipe reasons to update an order. Sometimes, you would only like to update data on an order, without triggering any other logic. For this, the patch endpoint would typically be a good fit.

Triggering workflows

An order update often involves a status update which should trigger a workflow in Omnium. A workflow contains workflow steps which triggeres actions configured for the current status. Examples of this could be to capture payment, send email/sms, book shipping, or reduce inventory. Workflows are an essencial part of how Omnium works. More information

There are endpoints specifically created for the purpose of updating order status and the workflow connected to the status: More information

Order/order-config#workflow-steps

Errors

The orders contain a list of errors in the property Errors. This is a list of OmniumEntityError, a class designed to capture detailed information about errors related to order processing. To add error messages to an order, simply add new items to this list.

{
	"id": "123",
	"orderNumber": "123",
	"errors": [
		{
			"Key": "Provider1Key",
			"Message": "This is a critical error.",
			"Details": "Detailed information about the error.",
			"Severity": "Error",
			"Occurred": "2022-10-16T12:34:56.789Z"
		},
		{
			"Key": "Provider2Key",
			"Message": "This is a warning.",
			"Details": "Additional details for the warning.",
			"Severity": "Warning",
			"Occurred": "2022-10-16T12:34:56.789Z"
		}
	]
}

Validate Order

Webhook validation for orders can be enabled from order settings in configuration. The validator will be run on all updates to the order from the UI. It’s possible to add custom validation using the webhook validator. The webhook validator will post the order. to a provided endpoint, and accept the validated order as response.

Add the webhook validator to Connectors in settings:

Required properties

PropertySample valueDescription
NamewebhookOrderValidatorName of Omnium connector provider. In this case it must be "webhookOrderValidator"
Hosthttps://acme.comEndpoint host
Implementations"IWebhookOrderValidator"Connector capabilities. Must include IWebhookOrderValidator.

Sample configuration

{
	"connectors": [
		{
			"name": "webhookOrderValidator",
			"host": "https://acme.com/api/ValidatorEndpoint",
			"isAuthenticatedManually": false,
			"timeOut": "00:00:00",
			"implementations": ["IWebhookOrderValidator"],
			"disableStandardErrorPolicy": false
		}
	]
}

Previous

API Reference

Next

Configuration

On this page