Customer Management

Overview

Omnium manages two distinct customer types: private customers (B2C) for individual consumers, and business customers (B2B) for companies and organizations. Both types share a common foundation — addresses, external IDs, consents, tags, custom properties — but differ in the features built on top.

Customer Data Model

Common Fields

Every customer — B2C and B2B — has the following:

For the full model definition, see the Swagger documentation: Private Customer model and Business Customer model.

Private Customer (B2C) Fields

In addition to the common fields:

Business Customer (B2B) Fields

In addition to the common fields:

API Endpoints

Omnium provides three sets of customer endpoints. Use the type-specific endpoints when you know the customer type; use the generic endpoint for operations that work across both types.

Generic Customers

Base URL: /api/customers

Private Customers (B2C)

Base URL: /api/privatecustomers

All generic operations, plus:

Business Customers (B2B)

Base URL: /api/businesscustomers

All generic operations, plus:

For complete endpoint details, see the Swagger documentation.

Creating Customers

From the API

Create a private customer:

POST /api/privatecustomers
{
  "firstName": "Sarah",
  "lastName": "Johnson",
  "email": "sarah@example.com",
  "phone": "+12125551234",
  "birthDate": "1985-03-20",
  "address": {
    "line1": "123 Main Street",
    "city": "New York",
    "postalCode": "10001",
    "countryCode": "US",
    "purposes": ["Shipping", "Billing"]
  },
  "storeIds": ["store-nyc"],
  "marketId": "market-us",
  "preferredLanguage": "en",
  "preferredCurrency": "USD",
  "tags": ["newsletter"],
  "consents": [
    {
      "type": "EmailMarketing",
      "date": "2026-02-14T10:00:00Z",
      "status": true,
      "source": "Web"
    }
  ]
}

Create a business customer with a contact person:

POST /api/businesscustomers
{
  "name": "Acme Industries LLC",
  "taxId": "US-87-1234567",
  "email": "info@acme-industries.com",
  "phone": "+13125559876",
  "address": {
    "line1": "456 Commerce Drive",
    "city": "Chicago",
    "postalCode": "60601",
    "countryCode": "US",
    "purposes": ["Billing"]
  },
  "contacts": [
    {
      "firstName": "Mike",
      "lastName": "Davis",
      "email": "mike@acme-industries.com",
      "phone": "+13125554321",
      "roles": ["Purchaser"],
      "isPrimaryContact": true,
      "notify": true
    }
  ],
  "storeIds": ["store-chicago"],
  "marketId": "market-us",
  "discountGroups": ["wholesale"]
}

Automatically from Orders

When an order arrives from your e-commerce platform, the Get or Create Customer workflow step can automatically create or update the customer record based on the order data. This behavior is configurable — see Customer creation control for the settings.

Searching Customers

The Search endpoint supports filtering, sorting, and pagination:

POST /api/privatecustomers/Search
{
  "query": "sarah",
  "marketIds": ["market-us"],
  "tags": ["newsletter"],
  "isInactive": false,
  "sortOrder": "ModifiedDescending",
  "take": 25,
  "page": 0
}

Available Filters

Scrolling for Large Datasets

For bulk exports or migrations, use the Scroll endpoint instead of paginated Search. Scroll handles large volumes efficiently by maintaining a cursor:

POST /api/privatecustomers/Scroll
{
  "marketIds": ["market-nor"],
  "take": 1000
}

The response includes a scrollId. Use it to retrieve the next batch:

GET /api/privatecustomers/Scroll/{scrollId}

Continue until no more results are returned. See the scrolling guide for details.

Delta Queries

To retrieve only customers that changed since your last sync:

GET /api/privatecustomers/GetAll?changedSince=2026-02-13T00:00:00Z&page=0&pageSize=100

See the delta queries guide for best practices.

Updating Customers

Full Update

Replaces the entire customer record. You must send all fields — omitted fields are reset to their defaults.

POST /api/privatecustomers/Update
{
  "id": "cust-12345",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "email": "sarah.new@example.com",
  ...
}

Partial Update (PATCH)

Only the fields you include are changed. Other fields are left untouched.

PATCH /api/privatecustomers/Patch
{
  "id": "cust-12345",
  "email": "sarah.new@example.com",
  "tags": ["newsletter", "vip"]
}

Bulk Operations

Add or update up to 100 customers in a single request:

PUT /api/privatecustomers/AddOrUpdateMany
[
  { "customerId": "cust-001", "firstName": "Sarah", ... },
  { "customerId": "cust-002", "firstName": "James", ... }
]

Customers that already exist (matched by ID) are updated; new customers are created.

Customer Groups

Customer groups let you organize customers for targeted promotions, pricing, or reporting.

PUT /api/CustomerGroups/Add
{
  "id": "wholesale-partners",
  "name": "wholesale-partners",
  "displayName": "Wholesale Partners",
  "properties": [
    { "key": "discountTier", "value": "gold" }
  ]
}

Assign a customer to a group by including the group reference in the customer's customerGroups list:

PATCH /api/businesscustomers/Patch
{
  "id": "cust-67890",
  "customerGroups": [
    { "id": "wholesale-partners", "name": "Wholesale Partners" }
  ]
}

External IDs and Integration

Customers can be linked to multiple external systems using the externalIds field. Each entry has a source (system name) and value (ID in that system):

"externalIds": [
  { "source": "Shopify", "value": "gid://shopify/Customer/12345" },
  { "source": "D365", "value": "CUST-00042" },
  { "source": "VoyadoContactId", "value": "abc-def-123" }
]

External IDs are used for:

• Import matching — When importing customers, Omnium uses external IDs to find existing records and avoid duplicates
• Cross-system lookups — Search for a customer by their ID in another system
• Export enrichment — Workflow steps can copy external IDs from the customer to the order for downstream integrations

You can highlight specific external ID types in the admin UI — see the configuration guide for details.

Addresses

Customers can have a primary address and a list of additional addresses. Each address has a purpose (or multiple purposes) that indicates how it's used:

An address includes: line1, line2, city, postalCode, countryCode, countryName, state, phone, email, name (label), and optional externalId for integration mapping.

B2B Contact Persons

Business customers can have multiple contact persons, each with their own role, contact details, and address. This models real-world organizations where different people handle purchasing, finance, and receiving.

Adding a Contact Person

POST /api/businesscustomers/{id}/AddContactPerson
{
  "firstName": "Emily",
  "lastName": "Clark",
  "email": "emily@acme-industries.com",
  "phone": "+13125558765",
  "roles": ["AccountsPayable"],
  "isPrimaryContact": false,
  "notify": true
}

Looking Up Companies by Contact

Find the business customer associated with a specific person:

GET /api/businesscustomers/GetBusinessCustomerByContactEmail?email=emily@acme-industries.com

B2B Credit Management

Business customers can have credit limits tracked per market:

"businessCustomerCredit": [
  {
    "marketId": "market-nor",
    "creditBalance": 50000,
    "creditLimit": 100000,
    "creditRemaining": 50000,
    "creditCurrency": "NOK",
    "isCreditDenied": false
  },
  {
    "marketId": "market-swe",
    "creditBalance": 20000,
    "creditLimit": 75000,
    "creditRemaining": 55000,
    "creditCurrency": "SEK",
    "isCreditDenied": false
  }
]

When isCreditDenied is true, the customer is blocked from placing orders on credit in that market.

B2B Assortment Restrictions

Business customers can have restricted product catalogs, so they only see the products relevant to their contract:

• Set isAssortmentRestricted to true
• Assign assortmentCodes that map to product categories

For detailed configuration, see Customer categories and assortment.

Customer Relations (B2B)

Business customers can be linked to each other using relations. Common patterns:

• Invoice receiver — Company A orders, Company B receives the invoice
• Goods receiver — Company A orders, Company C receives the delivery

Relations are configured in the customer configuration and assigned on the customer record via the customerRelations field.

Customer Merge and Deduplication

When duplicate customer records exist, you can merge them using the privacy endpoint:

GET /api/customerprivacy/ChangePrivateCustomerId?fromCustomerId=old-id&toCustomerId=keep-id

What happens during a merge:

• All orders, loyalty points, comments, and attachments from the source customer are moved to the target customer
• The source customer record is deleted
• An event is logged for audit purposes

For batch merges (up to 50 at a time):

POST /api/customerprivacy/ChangePrivateCustomerIdBatch
[
  { "fromCustomerId": "duplicate-1", "toCustomerId": "keep-1" },
  { "fromCustomerId": "duplicate-2", "toCustomerId": "keep-2" }
]

Business customers can also be merged using ChangeBusinessCustomerId.

Privacy and Anonymization (GDPR)

When a customer exercises their right to be forgotten, anonymize their data:

DELETE /api/customers/{id}

This:

• Removes all personal data (name, email, phone, addresses)
• Marks the customer as anonymized
• Preserves order records for business continuity (without personal data)
• Is irreversible

Consents

Omnium tracks customer consents for GDPR compliance and marketing preferences. Each consent records what was agreed to, when, and through which channel:

"consents": [
  {
    "type": "EmailMarketing",
    "date": "2026-02-14T10:00:00Z",
    "content": "I agree to receive marketing emails",
    "source": "Web",
    "status": true,
    "marketIds": ["market-nor"]
  }
]

Consent types are configured per tenant — see the consent management section in the configuration guide. Changes to consents are tracked in consentHistory for audit purposes.

Customer Club (Loyalty)

Omnium includes a built-in loyalty program with bonus points, tiers, and automated notifications. For setup and API usage, see the dedicated Customer Club guide.

Key concepts:

• Points are earned on purchases and can be used as payment via the BonusPoints payment provider
• Tiers segment members by spending level (e.g., Bronze, Silver, Gold)
• Birthday and sign-up points reward engagement milestones
• Points expire after a configurable number of days
• Workflow steps handle point calculation, earning, and cancellation throughout the order lifecycle

Integration with Orders

Customers and orders are connected through the order's customerId field. When an order is processed, workflow steps can:

1. Create or find the customer — The "Get or Create Customer" step matches the order's email/phone to an existing customer or creates a new one
2. Enrich the order — Copy customer properties, external IDs, or payment terms onto the order for downstream processing
3. Update the customer — Sync address changes from the order back to the customer record (if configured)
4. Calculate loyalty points — Award bonus points based on the order total

Related Documentation