Data In

Best practices for importing data to Omnium efficiently using batch operations and optimized endpoints.

Overview

This guide covers best practices for importing products, inventory, orders, and customers to Omnium efficiently..

TL;DR: Batch operations are gold!

When importing data to Omnium, batch operations are strongly recommended over single-item operations. Batch endpoints are optimized to handle high volumes efficiently and reduce API calls dramatically.

Inventory Updates

Strongly recommend using UpdateMany for inventory updates - even for single items. This is the most effective way to update inventory.

PUT /api/inventory/UpdateMany
 
[
  {
    "sku": "yellow-tshirt-small",
    "warehouseCode": "oslo-warehouse",
    "inventory": 25
  },
  {
    "sku": "yellow-tshirt-medium",
    "warehouseCode": "oslo-warehouse",
    "inventory": 30
  },
  {
    "sku": "yellow-tshirt-large",
    "warehouseCode": "oslo-warehouse",
    "inventory": 40
  }
]

Key Benefits:

Ignores unchanged inventory items
Only updates items with actual changes
Handles up to 1000 items per batch
Automatically inserts new items or updates existing ones
Enriches existing inventory items - preserves reservedInventory and other existing data
Optimal performance for bulk operations

Best Practice: Use UpdateMany even if you only have a single inventory update. The endpoint is optimized to handle both single and bulk operations efficiently.

Product Updates

Prefer batch operations (UpdateMany/PatchMany) for product updates. For specific single operations, use Patch.

Using PatchMany (recommended for product updates):

PATCH /api/products/PatchMany
 
[
  {
    "id": "yellow-tshirt_no",
    "description": "Updated high-quality cotton t-shirt with improved fabric blend"
  },
  {
    "id": "blue-jeans_no",
    "isActive": false
  }
]

Benefits:

Only updates fields that have actual changes
Handles up to 1000 products per batch
Optimal performance - skips unnecessary updates
Preserves existing product data

Using Patch for single operations:

PATCH /api/products/{productId}
 
{
  "description": "Updated product description"
}

Important: Batch operations do not create product versions, but are significantly more effective and faster.

Price Updates

Prices can be updated as part of the product (via api/products/PatchMany, for instance), but to ensure proper handling of existing prices, whether you want to retain or remove them, you should use the dedicated pricing endpoint

PUT /api/prices/AddMany
 
[
  {
    "productId": "yellow-tshirt",
    "prices": [
      {
        "marketId": "nor",
        "unitPrice": 349.00,
        "currencyCode": "NOK",
        "validFrom": "2024-01-01T00:00:00Z"
      }
    ]
  },
  {
    "productId": "blue-jeans",
    "prices": [
      {
        "marketId": "nor",
        "unitPrice": 799.00,
        "currencyCode": "NOK",
        "validFrom": "2024-01-01T00:00:00Z"
      }
    ]
  }
]

Benefits of dedicated price updates:

Automatically checks for actual price changes to avoid unnecessary updates
Optimized for high-frequency price updates from external systems
Handles complex pricing scenarios (customer groups, volume pricing, etc.)
If you are using "separate prices" you should always use this endpoint for price updates

Order Import

Batch import orders when importing from external systems. Use this only for orders that don’t need to trigger workflows, like import of POS orders, or imported orders from other (legacy?) systems:

POST /api/orders/ImportMany
 
[
  {
    "orderId": "EXT-12345",
    "storeId": "oslo-online",
    "marketId": "nor",
    "customer": {
      "email": "customer@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "orderLines": [
      {
        "skuId": "yellow-tshirt-medium",
        "quantity": 2,
        "unitPrice": 299.00
      }
    ]
  },
  {
    "orderId": "EXT-12346",
    "storeId": "oslo-online",
    "marketId": "nor",
    "customer": {
      "email": "another@example.com",
      "firstName": "Jane",
      "lastName": "Smith"
    },
    "orderLines": [
      {
        "skuId": "blue-jeans-32",
        "quantity": 1,
        "unitPrice": 799.00
      }
    ]
  }
]

Benefits:

Process multiple orders in a single API call
Reduced overhead and faster processing
Better error handling with batch results

Customer Import

Use batch endpoints for customer data:

PUT /api/PrivateCustomers/AddOrUpdateMany
 
[
  {
    "customerId": "CUST-001",
    "customerNumber": "42",
    "email": "frequent.shopper@example.com",
    "firstName": "Liv",
    "lastName": "Andersen",
    "gender": "Female",
    "birthDate": "1985-03-15T00:00:00Z",
    "phone": "+4798765432",
    "isCustomerClubMember": true,
    "bonusPoints": 1337,
    "tags": ["VIP"],
    "address": {
      "name": "Liv Andersen",
      "line1": "Storgata 15",
      "city": "Oslo",
      "postalCode": "0155",
      "countryCode": "NO",
      "countryName": "Norway",
      "email": "frequent.shopper@example.com",
      "phone": "+4799999999"
    }
  }
]

Summary: Data Import Best Practices

Inventory: Strongly recommend using UpdateMany - even for single updates
Products: Prefer UpdateMany/PatchMany for batch operations; use Patch for single operations
Prices: Use dedicated PUT /api/prices/AddMany endpoint
Orders: Batch import using ImportMany
Customers: Use batch AddMany endpoint

Recommended Batch Sizes

These are general recommendations for batch sizes per API call. Tune these based on your specific needs and entity complexity:

Entity Type	Recommended Batch Size	Notes
Inventory	1000	⚡ Optimized for high-volume updates
Products	500	Consider reducing if products have a combination of many variants, properties, or categories
Orders	250-500	Consider reducing for complex orders with many order lines (50+)
Customers	500	Reduce if customers have extensive address or contacts (typically for complex b2b customers)
Prices	500-2000	Use up to 2,000 when separate prices are enabled; otherwise align with your product batch size.

Important: These are starting points. Check your API response times and adjust batch sizes accordingly. Large products with extensive variants, properties, and categories should use smaller batch sizes (e.g., 250) to avoid timeouts and ensure reliable processing. The same applies to orders with many order lines or customers with complex data structures.

Best Practices Summary

Use UpdateMany for inventory
Use PatchMany/UpdateMany for products
Use dedicated Prices/AddMany endpoint for price updates
Batch import historical orders historical and customers when possible
Batch operations ftw!

Next Steps

Now that you understand data import patterns:

Review the Data Out for export strategies
Check out the Quick Start Guide for end-to-end examples