Digital Item Mapping Hub (DIMH) Integration

🔒 This is a strategic integration option available for select partners. Contact SRS API Support Team for access.

In a nutshell: DIMH eliminates the need to map your product catalog to SRS product IDs manually. Submit orders using your own product names and units of measure—DIMH automatically maps them to the correct SRS items before processing.

What DIMH solves:

✅ Automatically maps your product names to SRS catalog items

✅ Eliminates manual product ID lookups for every order

✅ Supports custom units of measure with automatic conversion

✅ Reduces line review workload with branch-specific mappings

Before you start: Complete Steps 1-4 to get your access token and validated customer account.

🔄 How DIMH Works

DIMH is a preprocessing wrapper that sits between your system and the standard Submit Order v2 endpoint. Here's the complete flow in 4 steps:

DIMH is a Wrapper: DIMH Submit Order is a preprocessing layer that maps your product names to SRS catalog items, then calls the standard Submit Order v2 endpoint. The response format is identical - you can submit synchronous or asynchronous orders just like the standard endpoint.

💡 Common Use Cases

DIMH is ideal for partners with existing product catalogs who want to avoid manual mapping:

ERP System Integration

Your system has its own product catalog with internal SKUs.

Without DIMH: Manual lookup of SRS product IDs for every item
With DIMH: Submit orders using your SKUs, automatic mapping

Custom Product Naming

Your field teams use custom product names that differ from SRS catalog.

Without DIMH: Translate product names manually before API calls
With DIMH: Use your product names directly, DIMH handles translation

Multi-Branch Operations

Different branches may have different product availability or naming conventions.

Without DIMH: Manage separate product catalogs per branch
With DIMH: Branch-specific mappings handled automatically

Understanding DIMH Mapping Process

🔍 Automatic Mapping Flow

First Request

You submit an order with customerItem and uom (do not include productName)

DIMH Lookup

System queries mapping database using:

customerCode (customer-specific mappings)

branchCode (branch-specific mappings)

customerItem (exact name matching - copied from customerItem field)

uom (unit of measure - prioritizes exact matches)

Exact UOM Match Priority

If multiple mappings exist for same product, only exact UOM matches are returned

Mapping Application

Mapped itemCode, productId, and final UOM are applied to line items

No Fallback

If no exact UOM match exists, item proceeds without mapping (not an error)

Critical Mapping Behavior: DIMH only uses mappings with exact UOM match. If your request has uom: "RL" but mapping exists only for uom: "SQ", the mapping will NOT be applied. This prevents incorrect UOM conversions.

✅ Required Fields for Mapping

Mandatory Fields

Must be provided for mapping to work:

✅ customerCode - Must be provided and valid

✅ branchCode - Must be provided and valid

✅ customerItem - Your product name (primary matching key)

✅ uom - Must exactly match mapping table entry

Not Used in Mapping Lookup

These fields are ignored during mapping:

❌ itemCode - Not used in mapping queries

❌ productId - Not used in mapping queries

❌ productOptions - Not used in matching logic

⚠️ productName - Deprecated (use customerItem instead)

Important: If customerCode or branchCode is missing, NO mappings will be retrieved (returns empty list, not an error).

Custom UOM Support: DIMH supports custom unit of measure conversions. Quantities are automatically converted and rounded up to prevent under-ordering.

DIMH Submit Order Endpoint

Submit orders using your product catalog instead of SRS product IDs.

API Call

Endpoint: POST /orders/dimh/Submit

Request Headers:

Authorization: Bearer {token}

Content-Type: application/json

Request Body

Click to expand: Full request body example below

📋 Click to view full request body example

{
  "sourceSystem": "SERVICETITAN",  // 🔑 Your integration identifier
  "customerCode": "SMO",  // 👤 Customer account number
  "jobAccountNumber": 78,  // 🔑 Job account number (numeric)
  "branchCode": "AMDEN",  // 🏪 Branch code
  "accountNumber": "SMO",  // 🎯 Account number
  "transactionID": "ANY-UNIQUE-STRING",  // 🔑 Unique transaction ID
  "transactionDate": "2023-05-11T10:49:34.187",  // 📅 Transaction timestamp
  "notes": "",  // 📝 Additional notes (optional)
  "shipTo": {
    "addressLine1": "1234 COUNTY LINE ROAD",
    "addressLine2": "",
    "addressLine3": "",
    "city": "ONTARIO",
    "state": "NY",
    "zipCode": "14519"
  },
  "poDetails": {
    "poNumber": "834325",  // 🔖 Purchase order number
    "reference": "",
    "jobNumber": "",
    "orderDate": "2021-04-12",
    "expectedDeliveryDate": "2021-04-15",
    "expectedDeliveryTime": "Anytime",
    "orderType": "WHSE",  // 📦 Order type (WHSE = Delivery)
    "shippingMethod": "Ground Drop"  // 🚚 Shipping method
  },
  "orderLineItemDetails": [
    {
      "customerItem": "MY PRODUCT SKU 001",  // ✅ Your internal product name
      "productOptions": "2 SQ/RL",  // 🎨 YOUR product options
      "quantity": 5,  // 🔢 Quantity to order
      "uom": "RL"  // 📏 YOUR unit of measure
    },
    {
      "customerItem": "MY PRODUCT SKU 002",  // ✅ Your internal SKU
      "productOptions": "123 LF/BD",
      "quantity": 1,
      "uom": "BD"
    }
  ],
  "customerContactInfo": {
    "customerContactName": "John Dough",
    "customerContactPhone": "9876543210",
    "customerContactEmail": "jdough@example.com",
    "customerContactAddress": {
      "addressLine1": "123 Main St",
      "city": "Salt Lake City",
      "state": "Utah",
      "zipCode": "84121"
    },
    "additionalContactEmails": [
      "test@example.com"
    ]
  }
}

📋 Key Line Item Fields:

customerItem: ✅ Use this field - Your internal product identifier (this is the correct field for DIMH integration)

productName: ⚠️ Deprecated - Do not include (maintained for legacy compatibility only)

productOptions: Your product options/variants (not used in mapping lookup)

quantity: Quantity to order (will be converted if custom UOM mapping exists)

uom: Your unit of measure (must exactly match mapping table for mapping to work)

Standard Pattern: Always use customerItem for your product names. Do not include productName in your request. The productName field is deprecated and maintained only for legacy compatibility.

Field Processing Rules (Legacy Compatibility):

✅ Standard Pattern: Fill only customerItem, omit productName → System automatically uses customerItem for mapping
⚠️ Legacy Compatibility: If productName is provided (deprecated pattern) → System applies concatenation rules for backward compatibility
Purpose: customerItem is the correct field for DIMH integration. productName exists only for legacy support.

Order Processing Flow

DIMH processes orders through 6 sequential steps:

Process Order Line Items

Apply customerItem/productName concatenation rules to ensure proper display on order acknowledgments.

Resolve Branch (if BranchCode = ANY)

Finds nearest eligible branch using latitude, longitude, maxMiles. Automatically sets branchCode to nearest branch. Returns error if no branch found within radius.

Resolve ShipTo Address (if ShipTo = null)

Auto-fetches address using customerCode and shipToSequenceNumber. Returns error if address cannot be found.

Apply Digital Item Mapping

Query mapping database with customerCode + branchCode + productName + uom

Filter for exact UOM matches only

Apply mapped itemCode, productId, option, final UOM

Convert quantity if custom UOM conversion exists

Transform to Submit Order Request

Convert DIMH request to standard SubmitOrderRequestV2 format and preserve all mapped values.

Submit Order

Call standard Submit Order v2 endpoint and return response to caller.

Important: Steps 2 and 3 are optional validations. If they fail, the process returns an error immediately. Step 4 (mapping) never fails - if no mapping exists, the order proceeds with original values.

Successful Response

{
  "message": "Order Submitted",  // ✅ Order successfully submitted
  "transactionID": "ANY-UNIQUE-STRING",  // 🎯 Your unique transaction ID
  "orderID": "35818786",  // 🔑 SRS order ID for tracking
  "queueID": null  // 🔄 Queue ID (null for synchronous orders)
}

Order Processing: DIMH automatically maps your product names to SRS items before submitting the order. Response format matches standard Submit Order v2 endpoint. Mapping failures do NOT prevent order submission - items without mappings proceed with original values.

🧪 Additional DIMH Endpoints (Experimental)

The following endpoints exist but are not actively used in current integrations. They are mentioned here for completeness.

DIMH Pricing Endpoint

Endpoint: POST /products/v2/dimh/price

Get real-time pricing using your product names instead of SRS product IDs. Works similarly to DIMH Submit Order but returns pricing information only.

Status: ⚠️ Available but not widely adopted. Most partners use standard Pricing v2 endpoint with known product IDs.

DIMH Items Endpoint

Endpoint: POST /orders/dimh/items

Fetch available items with mapping support.

Status: 🧪 Experimental - not documented or recommended for production use.

Fetch Opt-In DIMH Customers Endpoint

Endpoint: GET /orders/dimh/customers

Retrieve list of customers who have opted into DIMH service.

Status: 🔒 Internal analytics endpoint - not intended for partner integrations.

Focus on Submit Order: The primary DIMH integration is Submit Order DIMH. The other endpoints are experimental or for internal use. Contact SRS API Support Team if you need information about these additional endpoints.

⚙️ Advanced Features

🛡️ Request Validation & Error Handling

DIMH applies strict validation rules with specific error messages:

1️⃣ Branch Resolution Validation (when branchCode = 'ANY')

2️⃣ ShipTo Address Validation (when shipTo = null)

3️⃣ Mapping Validation (always runs, never fails)

Critical Behavior: Mapping failures are warnings, not errors. Orders proceed even if:

No mapping exists for a product
UOM doesn't match exactly
CustomerCode or BranchCode missing (no mappings retrieved)
Custom UOM conversion factor is missing

These scenarios are logged but do NOT stop order submission.

🔄 Custom UOM Conversion

DIMH supports automatic unit of measure conversion with quantity rounding.

How it works:

You submit order

uom: "BOX" and quantity: 10

Mapping exists

conversion_factor: 2.5 (1 BOX = 2.5 BD)

DIMH calculates

10 × 2.5 = 25

Check rounding

Quantity is whole number → No rounding needed

Order submitted

uom: "BD" and quantity: 25

Rounding Behavior:

Whole Numbers: No rounding applied (e.g., 10 × 2 = 20)

Decimals: Always rounded UP to prevent under-ordering (e.g., 10 × 2.3 = 23, not 22)

📊 Example with Rounding

Quantity Rounding: All fractional quantities are rounded UP to prevent under-ordering. A request for 7 BOXES with 1.5x conversion becomes 11 SQ (not 10).

Missing Conversion Data:

If conversion data is not configured for a custom UOM, conversion is skipped

Item proceeds with original UOM and quantity (not an error)

Contact SRS API Support Team if you encounter this scenario

Custom UOM Setup: Contact SRS API Support Team to configure custom UOM mappings and conversion factors. Provide your UOM codes and desired conversion ratios (e.g., "1 CARTON = 5 BD").

🔀 How DIMH Handles Multiple Mappings

When multiple mappings exist for the same product name, DIMH applies strict UOM filtering:

Priority Rules:

1️⃣ Exact UOM Match REQUIRED

Only mappings that exactly match your requested UOM (case-insensitive)

2️⃣ Duplicate Elimination

If multiple exact UOM matches exist, first one is selected

3️⃣ No Fallback

If no exact UOM match exists, item proceeds without mapping

4️⃣ Incomplete Mappings Excluded

Mappings with missing conversion data are automatically excluded

📋 Example Scenario: Multiple UOM Mappings

No Partial Matching: DIMH does NOT use "close enough" UOM matching. If your request has uom: "ROLL" but the mapping is configured for "RL", NO mapping is applied (exact match required).

📍 Automatic Branch Resolution

DIMH supports automatic branch resolution when you don't have a specific branch preference.

Request with branchCode: "ANY":

{
  "branchCode": "ANY",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "maxMiles": 50
}

DIMH Response:

Finds nearest eligible branch within maxMiles

Automatically sets branchCode to nearest branch

Returns error if no branches found within range

You're Ready with DIMH!

You can now:

✅ Submit orders with your product catalog

✅ Leverage automatic product mapping

✅ Use custom UOM conversions

✅ Benefit from branch-specific mappings

🎯 Next Steps

Setup Webhooks

Learn how to receive real-time order status updates.

Error Handling

Learn how to handle mapping failures and edge cases.

Best Practices

Optimize your DIMH integration for production use.

❓ Frequently Asked Questions

What happens if customerCode or branchCode is missing?

Can I use DIMH and standard endpoints together?

What happens if no mapping exists for a product?

What if my UOM doesn't match the mapping table exactly?

Can I request specific mappings in advance?

How do I know which products need mappings?

Does DIMH support product substitutions?

What happens when conversion results in fractional quantities?

Can the same productName have different mappings for different UOMs?

Is itemCode or productId used in mapping lookup?

What if branchCode is ANY?

Can DIMH handle asynchronous order submission?

What happens with mixed items (some mapped, some not)?

📧 Request DIMH Access

Email: APISupportTeam@srsdistribution.com

Include:

Your client ID and source system identifier

Sample product catalog (10-20 items)

Custom UOM requirements (if any)

Expected order volume

Response time: 2-3 business days for access approval and configuration

Ready to simplify your integration? Contact SRS API Support Team to enable DIMH for your account! 🚀

DIMH

Digital Item Mapping Hub (DIMH) Integration#

🔄 How DIMH Works#

💡 Common Use Cases#

Understanding DIMH Mapping Process#

🔍 Automatic Mapping Flow#

✅ Required Fields for Mapping#

DIMH Submit Order Endpoint#

API Call#

Request Body#

Order Processing Flow#

Successful Response#

🧪 Additional DIMH Endpoints (Experimental)#

⚙️ Advanced Features#

🛡️ Request Validation & Error Handling#

🔄 Custom UOM Conversion#

🔀 How DIMH Handles Multiple Mappings#

📍 Automatic Branch Resolution#

You're Ready with DIMH!#

🎯 Next Steps#

❓ Frequently Asked Questions#

📧 Request DIMH Access#

Digital Item Mapping Hub (DIMH) Integration

🔄 How DIMH Works

💡 Common Use Cases

Understanding DIMH Mapping Process

🔍 Automatic Mapping Flow

✅ Required Fields for Mapping

DIMH Submit Order Endpoint

API Call

Request Body

Order Processing Flow

Successful Response

🧪 Additional DIMH Endpoints (Experimental)

⚙️ Advanced Features

🛡️ Request Validation & Error Handling

🔄 Custom UOM Conversion

🔀 How DIMH Handles Multiple Mappings

📍 Automatic Branch Resolution

You're Ready with DIMH!

🎯 Next Steps

❓ Frequently Asked Questions

📧 Request DIMH Access