Configuration

Omnium market setup

All orders in Omnium require a market ID. The market contains lots of options, including:

• Language and localization
• Region and country
• Currency
• Tax configuration
• Shipments
• Number options
• Email settings
• Available connectors

There are no limitations on the number of markets. Based on the requirements, a market could be set up by country, state, or region, brand, or concept – or a combination of the above.

Considerations for market setup

Product languages and currencies

Markets are used to determine the product language and currency for placed orders. As a rule of thumb, every currency and/or product language should have its own market. Stores can be related to multiple markets, so in cases where a single store serves multiple markets (i.e., a web store that sells products in multiple countries with different currencies and/or languages), orders placed for the store in question will get its product language and price currency based on the market the order is placed in.

B2B vs B2C

Another use case for markets is separation between B2C and B2B. In market settings, it is possible to configure whether prices and orders include or exclude tax. The MarketType property can be used to distinguish between B2C and B2B markets.

Customer communication

Communication with customers is also affected by the market structure. It is possible to design custom email templates for each market to support different languages and brands/concepts. The WebsiteUrl and LogoUrl properties can be customized per market for branded communications.

Market model

Core properties

Localization properties

Product content language fallback

When retrieving product content, the system follows this fallback order:

1. Market's ProductContentLanguage if set
2. Default market's ProductContentLanguage if available
3. Tenant's DefaultProductContentLanguageCode from product settings
4. English ("en") if available in tenant product settings
5. First available language from tenant product settings

Tax configuration

Tax calculation behavior

When IsTaxExcluded is set to true:

• Order line tax rate is set to 0
• PlacedPrice uses the ex-tax value (PlacedPriceExclTax)
• No tax calculations are applied to the order
• Discounts are also adjusted to use ex-tax values

Payment configuration

Market groups

Market groups allow you to organize multiple markets together for shared configuration and reporting. Groups can represent regions, brands, or business units.

Market group model

Sample

{
  "MarketGroups": [
    {
      "GroupId": "nordic",
      "GroupName": "Nordic Region",
      "TemplateSettings": {
        "DefaultEmailTemplate": "nordic-template"
      }
    },
    {
      "GroupId": "central-europe",
      "GroupName": "Central Europe"
    }
  ]
}

Use cases

• Regional grouping: Group markets by geographic region (Nordic, Central Europe, North America)
• Brand separation: Group markets by brand identity for multi-brand retailers
• ERP integration: Use MarketGroupId as CompanyId for Dynamics 365 or other ERP systems
• Shared templates: Apply email templates at the group level instead of per-market

Return charges

Return charges define the default costs applied when processing returns. These settings can be configured per market and optionally overridden per shipment method.

Return charges model

Return cost behavior

The return cost application follows this logic:

1. Check Market.ReturnCharges.ReturnCostDefaultDisabled
2. If false (enabled by default), the ReturnCost amount is automatically added to returns
3. If true (disabled by default), returns are created without the charge
4. Individual shipment methods can override this behavior via ShipmentOption.ReturnCostDefaultEnabled

Sample

{
  "ReturnCharges": {
    "ReturnCost": 49.00,
    "NotPickedUpCost": 99.00,
    "ReturnCostDefaultDisabled": false
  }
}

Number options

Number options configure how sequential identifiers are generated for orders, carts, returns, customers, and other entities. Each market can have its own numbering sequences, or share sequences across markets.

Number options model

Number service types

Supported number types

Resolution order

When determining which number options to use, the system follows this priority:

1. Market-specific NumberOptions for the requested NumberType
2. Tenant NumberOptions with matching MarketGroupId
3. Tenant NumberOptions without MarketGroupId
4. Tenant NumberOptions with matching NumberType
5. Default: GuidNumberService (for CustomerNumberOptions and others)

Order types can override this for order numbers by referencing a number option directly by its Key. See order number generation.

Sample

{
  "NumberOptions": [
    {
      "NumberType": "OrderNumberOptions",
      "Key": "order-counter",
      "Prefix": "ORD-",
      "StartSequence": 10000,
      "Service": "SequentialMarketNumberService",
      "IsReadOnly": true
    },
    {
      "NumberType": "ReturnNumberOptions",
      "Key": "return-counter",
      "Prefix": "RET-",
      "StartSequence": 1000,
      "Service": "SequentialNumberService"
    },
    {
      "NumberType": "CustomerNumberOptions",
      "Service": "GuidNumberService"
    }
  ]
}

This configuration produces:

• Order numbers: ORD-10000, ORD-10001, ORD-10002 (per market)
• Return numbers: RET-1000, RET-1001, RET-1002 (global)
• Customer IDs: Random GUIDs

Shipment options

Shipment options define the available shipping methods for a market, including provider configuration, pricing, and delivery settings.

Core shipment properties

Provider configuration

Pricing configuration

Service point configuration

Visibility and behavior

Default package dimensions

Sample

{
  "ShipmentOptions": [
    {
      "ShippingMethodId": "bring-servicepakke",
      "ShippingMethodName": "SERVICEPAKKE",
      "Label": "Pickup at Post Office",
      "Description": "Delivered to your nearest post office within 2-4 days",
      "ShipmentDeliveryType": "PickUp",
      "ShippingGateway": "Bring",
      "ShipmentProduct": "SERVICEPAKKE",
      "ShippingSubTotal": 79.00,
      "ShippingSubTotalExclTax": 63.20,
      "TaxRate": 25,
      "GetServicePoints": true,
      "ServicePointRequired": true,
      "DeliveryTime": "2-4 business days",
      "IsDefaultShipment": false,
      "HideInOms": false,
      "HideFromApi": false,
      "DefaultPackage": {
        "WeightInKg": 1.0,
        "DefaultDimensions": {
          "LengthInCm": 30,
          "WidthInCm": 20,
          "HeightInCm": 15
        }
      }
    },
    {
      "ShippingMethodId": "home-delivery",
      "ShippingMethodName": "HOME_DELIVERY",
      "Label": "Home Delivery",
      "Description": "Delivered to your doorstep",
      "ShipmentDeliveryType": "Delivery",
      "ShippingGateway": "Bring",
      "ShipmentProduct": "PA_DANSEN",
      "ShippingSubTotal": 149.00,
      "TaxRate": 25,
      "DeliveryTime": "1-3 business days",
      "IsDefaultShipment": true,
      "ProviderNotification": true
    }
  ]
}

Email client settings

Email client settings configure how emails are sent for a market, including SMTP settings, sender addresses, and template references.

Email client settings model

Sample

{
  "EmailClientSettings": {
    "Type": "SendGrid",
    "KeyName": "sendgrid-api-key",
    "StandardEmailAddress": "orders@mystore.com",
    "InBoundEmailAddress": "support@mystore.com",
    "InBoundEmailFromName": "My Store Support",
    "LanguageCode": "en"
  }
}

Template settings

Template settings configure which email and document templates are used for various entities like orders, carts, and projects.

Template settings model

Template reference settings

Project template references

Sample

{
  "TemplateSettings": {
    "DefaultEmailTemplate": "standard-order-confirmation",
    "OrderTemplates": [
      {
        "TemplateReference": "standard-order",
        "DisplayName": "Standard Order",
        "TranslateKey": "Template_StandardOrder"
      },
      {
        "TemplateReference": "gift-order",
        "DisplayName": "Gift Order",
        "TranslateKey": "Template_GiftOrder"
      }
    ],
    "ProjectTemplateReferences": {
      "CustomerCommentTemplate": "customer-project-comment",
      "InternalCommentTemplate": "internal-project-comment"
    }
  }
}

Invoice template

InvoiceTemplate replaces the standard PDF layout of invoices, credit notes and receipts. It is optional: when no template is set, the PDF uses the standard layout. Set it in the notification template settings, on the tab for a market, a market group or the default for all markets.

Which template a document uses

Omnium uses the first template that is set, in this order:

1. InvoiceTemplate on the document's market.
2. InvoiceTemplate on the market group that the market belongs to (MarketGroupId).
3. InvoiceTemplate in the default template settings for all markets.
4. The standard layout.

A document with no market starts at step 3. The same template is used everywhere an invoice PDF is made: the order's Invoices tab, GET api/Invoices/GetAsPdf/{id}, the invoice notification and the shipment receipt attachment on order notifications.

When the chosen file is missing, is not a .json file or has no html content, Omnium uses the standard layout and logs a warning that names the file and the document. A broken template never stops a PDF or an email.

The template file

The template is a .json file in the tenant's template container, made in the same email designer as the order templates. Omnium uses its html content.

Start from the starter invoice template rather than an empty design. It has the standard layout, every placeholder and the styles the generated parts need. Its styles apply only inside its omnium-invoice wrapper, so they do not change the designer's own layout. Find it in the demo content of the template file manager, copy it and change it. If your environment does not have it in the demo content yet, contact Omnium.

Omnium fills the template with the same values as the standard layout, so invoices, credit notes and receipts print the same data and only the layout changes. Margins, paper format and custom fonts come from the tenant's PDF settings.

The template must:

• Hold {ORDERLINES} inside a <table> with a matching header row. The placeholder becomes table rows. On a receipt each row has an extra VAT rate cell, and {TAX_RATE_HEADER_HTML} adds the matching heading.
• Define the CSS classes rightUpperInfo, floatRight and taxSummary, which the generated parts use.

A placeholder that the template leaves out is not printed. Text that the template adds is printed as written, in every language.

Placeholders

On an invoice, the receipt parts print nothing. On a receipt, the payment terms become the paid line, and the payments and the VAT summary per rate appear.

Things to know

• An invoice or a receipt is an accounting document. Keep the content the law requires: the number, the date, the seller with organization number and VAT registration, the lines, the VAT per rate and the totals. The starter template has all of it. Omnium does not check a custom template.
• Put the legal seller details of a receipt in the stored seller placeholders and in the document footer, {INVOICE_FOOTER}. The store placeholders show the store as it is when the PDF is made, so they can differ from the store as it was when the receipt was issued.
• A document is always rendered with the template that applies at that moment. A new template therefore also changes how documents issued earlier look when you download them again. The numbers, lines and payments on a receipt and its stored seller placeholders stay the same. The logo and the store placeholders show the current values.
• The designer is made for email. A long list of lines breaks across pages where the browser decides, and no header repeats on each page.
• Change the file through Omnium. A file changed directly in blob storage can stay cached for up to 24 hours.

{
  "TemplateSettings": {
    "InvoiceTemplate": "faktura-nor.json"
  }
}

Phone format settings

Phone format settings control how phone numbers are validated and formatted for a market.

Phone format settings model

Phone format

Sample

{
  "PhoneFormatSettings": {
    "RequireCountryCode": true,
    "UsePlusInCountryCode": true,
    "DefaultCountryCode": "47",
    "ExpectedPhoneNumberFormats": [
      {
        "CountryCode": "47",
        "MinExpectedNumberLength": 8,
        "MaxExpectedNumberLength": 8
      },
      {
        "CountryCode": "46",
        "MinExpectedNumberLength": 9,
        "MaxExpectedNumberLength": 10
      }
    ]
  }
}

Connectors

Markets can have market-specific connector configurations for integrating with external systems. Connectors can be restricted to specific markets or market groups.

For full connector configuration details, see the Integrations documentation.

Market restriction properties

Complete market configuration example

{
  "Markets": [
    {
      "MarketId": "NOR",
      "MarketName": "Norway",
      "IsDefaultMarket": true,
      "IsActive": true,
      "MarketType": "B2C",
      "MarketGroupId": "nordic",
 
      "Language": "Norwegian",
      "LanguageCode": "no",
      "IsoLanguageCode": "nb-NO",
      "CountryCode": "NO",
      "Currency": "NOK",
      "ProductContentLanguage": "no",
 
      "IsTaxExcluded": false,
      "ShowOrderLinesExTax": false,
      "DefaultTaxRate": 25,
      "DefaultVatType": 3,
      "DefaultPaymentType": "Card",
 
      "WebsiteUrl": "https://www.mystore.no",
      "LogoUrl": "https://cdn.mystore.com/logos/norway.png",
      "DocumentFooter": "<p>My Store AS | Org.nr: 123456789 | support@mystore.no</p>",
 
      "ReturnCharges": {
        "ReturnCost": 49.00,
        "NotPickedUpCost": 99.00,
        "ReturnCostDefaultDisabled": false
      },
 
      "NumberOptions": [
        {
          "NumberType": "OrderNumberOptions",
          "Key": "nor-orders",
          "Prefix": "NO-",
          "StartSequence": 10000,
          "Service": "SequentialMarketNumberService"
        }
      ],
 
      "ShipmentOptions": [
        {
          "ShippingMethodId": "bring-servicepakke",
          "ShippingMethodName": "SERVICEPAKKE",
          "Label": "Hent i Posten",
          "ShipmentDeliveryType": "PickUp",
          "ShippingGateway": "Bring",
          "ShipmentProduct": "SERVICEPAKKE",
          "ShippingSubTotal": 79.00,
          "TaxRate": 25,
          "GetServicePoints": true,
          "IsDefaultShipment": true
        }
      ],
 
      "EmailClientSettings": {
        "StandardEmailAddress": "ordre@mystore.no",
        "LanguageCode": "no"
      },
 
      "PhoneFormatSettings": {
        "RequireCountryCode": true,
        "UsePlusInCountryCode": true,
        "DefaultCountryCode": "47",
        "ExpectedPhoneNumberFormats": [
          {
            "CountryCode": "47",
            "MinExpectedNumberLength": 8,
            "MaxExpectedNumberLength": 8
          }
        ]
      }
    },
    {
      "MarketId": "SWE",
      "MarketName": "Sweden",
      "IsDefaultMarket": false,
      "IsActive": true,
      "MarketType": "B2C",
      "MarketGroupId": "nordic",
 
      "Language": "Swedish",
      "LanguageCode": "sv",
      "IsoLanguageCode": "sv-SE",
      "CountryCode": "SE",
      "Currency": "SEK",
      "ProductContentLanguage": "sv",
 
      "IsTaxExcluded": false,
      "DefaultTaxRate": 25,
 
      "WebsiteUrl": "https://www.mystore.se",
 
      "ReturnCharges": {
        "ReturnCost": 49.00,
        "ReturnCostDefaultDisabled": false
      },
 
      "NumberOptions": [
        {
          "NumberType": "OrderNumberOptions",
          "Key": "swe-orders",
          "Prefix": "SE-",
          "StartSequence": 10000,
          "Service": "SequentialMarketNumberService"
        }
      ]
    },
    {
      "MarketId": "B2B-NOR",
      "MarketName": "Norway B2B",
      "IsDefaultMarket": false,
      "IsActive": true,
      "MarketType": "B2B",
 
      "Language": "Norwegian",
      "LanguageCode": "no",
      "IsoLanguageCode": "nb-NO",
      "CountryCode": "NO",
      "Currency": "NOK",
 
      "IsTaxExcluded": true,
      "ShowOrderLinesExTax": true,
      "DefaultTaxRate": 25
    }
  ],
 
  "MarketGroups": [
    {
      "GroupId": "nordic",
      "GroupName": "Nordic Region"
    }
  ]
}