SfSkills Domains Docs GitHub

Home / data / commerce-inventory-data

commerce-inventory-data

Use when managing inventory data in Salesforce Omnichannel Inventory (OCI) — covers stock level APIs, warehouse location mapping, IMPEX bulk upload, inventory availability queries, reservation management, and reorder point design. NOT for Field Service van stock, ProductItem and ProductTransfer — use admin/fsl-inventory-management. NOT for designing OCI integration and split-order fulfillment routing — use architect/order-management-architecture.

Open the skill folder on GitHub

Commerce Inventory Data

This skill activates when a practitioner needs to manage inventory data in Salesforce Omnichannel Inventory (OCI) — the cloud-native inventory management layer for Commerce Cloud. It covers the two primary data paths (real-time API updates and bulk IMPEX imports), the critical throughput limits on each, and the scheduling constraints that prevent data corruption when running full IMPEX imports in close succession.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

OCI Location Hierarchy

OCI organizes inventory into a two-level location hierarchy:

When mapping from a WMS (warehouse management system) to OCI, each physical location maps to an OCI Location. Location Groups define the inventory pool visible to each storefront.

Two Data Paths: API vs. IMPEX

Real-Time API (batchInventoryUpdate):

Bulk IMPEX:

Reservation Management

OCI supports inventory reservation for Commerce checkout:

Reservations have an expiration time. Expired reservations are automatically released, returning inventory to the available pool.

Common Patterns

Pattern 1: Nightly Bulk Sync via IMPEX

When to use: WMS provides a nightly inventory snapshot for all SKUs and locations. Volume exceeds what real-time API can handle efficiently.

How it works:

  1. WMS exports inventory snapshot as CSV (Location, SKU, OnHandQuantity, SafetyStockCount)
  2. Compress file with gzip if > 100 MB
  3. Upload to OCI IMPEX endpoint as a Full import job
  4. Poll import job status until complete
  5. Validate: query OCI availability API for a sample SKU set and compare to WMS source

Why not real-time API for bulk: batchInventoryUpdate at 100 SKUs per call would require thousands of API calls for a large catalog. IMPEX is designed for bulk inventory snapshots.

Pattern 2: Real-Time Update for Order Fulfillment Events

When to use: An order is fulfilled in the WMS and stock count must be decremented immediately in OCI before the next page load.

How it works:

  1. WMS sends webhook on fulfillment event
  2. Integration layer calls POST /commerce/oci/reservation/actions/fulfillments with the reservation ID
  3. OCI decrements on-hand count and closes the reservation
  4. Storefront availability query reflects updated count within seconds

Why not wait for nightly IMPEX: Customers checking the storefront after a product sells out need accurate availability. Real-time reservation fulfillment keeps OCI synchronized with WMS without waiting for the next batch window.

Decision Guidance

SituationRecommended ApproachReason
Nightly full inventory syncIMPEX Full import (gzip-compressed for > 100 MB)Designed for bulk snapshots; handles large catalog efficiently
Real-time stock decrements < 100 SKUsbatchInventoryUpdate REST APISynchronous; immediate confirmation
Real-time stock update > 100 SKUsBatch into multiple batchInventoryUpdate callsHard limit of 100 SKUs per call
Order fulfillment stock decrementOCI reservation fulfillment actionCloses reservation and decrements count atomically
IMPEX schedulingSpace full imports by at least 1 hour minimumBack-to-back full imports risk data corruption
FSL technician inventoryField Service Lightning inventory moduleOCI is for Commerce inventory, not FSL field stock
  1. Design location hierarchy — Map physical warehouses to OCI Locations. Create Location Groups matching the inventory pool for each Commerce store. Document Location IDs and Location Group IDs.
  2. Select data path — Decide between nightly IMPEX (for bulk snapshot sync) and real-time API (for event-driven updates). Many implementations use both: IMPEX for nightly reconciliation and API for real-time reservation/fulfillment.
  3. Design IMPEX file format — Prepare the CSV schema for inventory records: Location Identifier, SKU, OnHandQuantity, SafetyStockCount. Confirm gzip compression is applied for large files.
  4. Configure IMPEX scheduling — Schedule nightly full IMPEX with sufficient spacing from any other full imports. Document the minimum interval between runs in the operations runbook.
  5. Implement reservation flow — For Commerce checkout, integrate the reservation API call into the order submission flow. Set reservation expiration time matching checkout session timeout.
  6. Validate inventory availability — After each IMPEX or API update, query the OCI availability endpoint for a sample of SKUs and confirm values match the source system.
  7. Monitor for import errors — Poll IMPEX job status endpoint after each upload. Log failures to an operations alert system — silent IMPEX failures cause stale inventory without any visible error in the storefront.

Review Checklist

Salesforce-Specific Gotchas

  1. batchInventoryUpdate is capped at 100 SKUs per call — Any call exceeding 100 SKU-location pairs is rejected. Integration code must batch updates into chunks of ≤100. This limit applies to the real-time API, not IMPEX.
  2. Full IMPEX imports must not run back-to-back — Running full inventory imports in rapid succession (within minutes) risks overlapping write operations on the OCI inventory store, which can produce corrupted availability data. Salesforce documents that full imports require spacing between runs. Enforce a minimum interval in job scheduling.
  3. OCI exposes inventory at Location Group level, not individual Location level, to Commerce — The Commerce storefront availability display aggregates inventory across all Locations in the associated Location Group. Individual warehouse stock levels are not surfaced to the buyer. Design reporting and ops dashboards at the Location level but configure storefront availability at the Location Group level.

Output Artifacts

ArtifactDescription
Location hierarchy mappingPhysical warehouse to OCI Location and Location Group mapping document
IMPEX file specificationCSV column structure, compression requirements, and scheduling constraints
API integration designbatchInventoryUpdate call batching pattern and reservation/fulfillment flow
Monitoring runbookIMPEX job status polling, error alerting, and nightly validation queries

Package files