Use the New product sync upgrade assistant when a Shopify connection shows Upgrade to new product sync or Disable old product sync. The assistant verifies that the current sync is available, deactivates the legacy pipeline, and prepares the shop for the current setup flow.

Confirm readiness

1. Review the HotWax Commerce release and per-shop job status.

2. Check each required system message type, job, Data Manager configuration, and data document.

3. Select Refresh checks after the technical team adds a missing artifact.

4. Continue only when every required artifact is available.

Use Copy details to share missing artifact IDs with the technical team.

1. Review the legacy system message types, service jobs, and unfinished system messages.

2. Deactivate active legacy message types.

3. Finish active legacy service jobs.

4. Cancel unfinished legacy system messages.

When 50 or more unfinished messages appear, avoid canceling them in bulk from the page. The app warns that this can create many API requests and timeouts. Ask the technical team to process the messages in the background.

1. Configure the per-shop sync job when the assistant shows Configure.

2. Enable any paused shared jobs.

3. Select Go to new product sync setup.

Use the Company App to manage user accounts and the access they receive through Security Groups.

Choose a task

• Create a user

• Manage a user

• Manage Security Groups and App Permissions

User access has two parts:

• A Security Group assigns permissions to its members.

• App Permissions shows which Security Groups and users can access each application capability.

Review both areas when a user lacks access to a page or action.

A Product Store represents a brand or storefront in HotWax Commerce. Create the Product Store before you configure its Shopify connection, facilities, inventory, and order workflows.

Collect the following information:

• Brand or storefront name

• Product Store ID

• Default currency

Use this guide when a bulk employee import fails or rejects records. For the import procedure, see .

Check the import file for:

• Missing required columns

• Duplicate username or external ID

• Invalid email format

Use Company to trace access from the user to a Security Group and then to the required App Permission.

Confirm the user

1. Open the Company App.

2. Go to Users.

3. Find the affected user.

4. Confirm that login shows an active status.

5. Confirm that the user is active.

1. Open the user's clearance section.

2. Review the assigned Security Groups.

3. Identify the group expected to grant the missing access.

4. Add the approved group when missing.

1. Go to Users > App Permissions.

2. Open the affected application.

3. Select the permission for the missing page or action.

4. Confirm that the expected Security Group appears under group access.

Use the live App Permissions catalog instead of a copied list of permission IDs.

Fulfillment and pickup applications can also require facility association.

1. Return to the user.

2. Review the assigned facilities.

3. Add the facility where the user needs to work.

4. Save the user.

1. Ask the user to sign out.

2. Ask the user to sign in again.

3. Open the exact page or repeat the exact action.

4. Record the missing page or action when access still fails.

Contact support with the user ID, Security Group, App Permission, facility, and exact action. Keep the user's password out of the support request.

Use Job Manager to audit files processed through Data Manager.

1. Open MDM > File history.

2. Search for the file, configuration, or log identifier.

3. Filter by status, priority, error state, or configuration.

4. Open the file.

5. Review the timeline, original data, and errors.

Read and for the complete workflow.

Use Job Manager for operator file submissions.

1. Open MDM > Manual uploads.

2. Find the required configuration.

The HotWax Commerce Import App is designed specifically for merchandisers to manage purchase order inventory and regular inventory imports from external systems into HotWax Commerce using CSV files. Since inventory management at the enterprise level is a critical function, access to the Import App is restricted to users responsible for these tasks. Therefore, only users with "IMPORT_APP_VIEW" permissions can access the app. Additional permissions are required to manage specific processes within the Import App, ensuring that only authorized personnel can execute sensitive tasks.

Below is a list of all the actions available in the Import App, along with the specific permissions needed to perform them.

Start in Job Manager with the exact file or log identifier.

1. Open MDM > File history.

2. Search for the file, configuration, or log identifier.

Clone settings when a target Product Store should use approved configuration from an existing source Product Store.

Cloning overwrites the selected categories on the target Product Store. The clone page provides no undo action.

1. Open the Company App.

2. Go to Product Store.

Steps:

1. Enable Postfix Service:

• Postfix is a Sendmail-compatible mail transport agent that ensures secure, fast, and easy email configuration.

• The technical team can enable the Postfix service on your server and provide you with instance-specific Postfix details.

2. Configure Postfix Relay Host:

Security Groups bundle permissions for a role. App Permissions provides an application-centered view of those permissions and the users who receive access.

1. Open the Company App.

2. Go to Users > Security Groups.

Use the guide that matches the failure:

Capture the configuration identifier, file or log identifier, current status, first error, and timestamps before you change a service, path, or execution mode.

To access the logs for import and export jobs, navigate to the MDM (Master Data Management) > EXIM (Export-Import) page from the Hamburger menu. Here, under the Shopify section, various MDM pages display the processes between Shopify and HotWax Commerce. These pages include:

• Shopify GraphQL job: Records all GraphQL files uploaded from Hotwax Commerce to Shopify for API calls like adding pre-order catalogs or tags.

• Shopify Order MDM: Contains files generated from Shopify for importing orders into Hotwax Commerce.

• Shopify Order Return:

Data Manager configuration defines how files enter and leave the HotWax Commerce Order Management System. Use these administration pages to maintain import services, execution modes, templates, and queue behavior.

Use Job Manager for daily operations:

• Upload a file manually

• Monitor file processing

1. Open the Order Management System.

2. Open the main menu.

3. Select Settings.

4. Select Data Manager Configurations.

The exact administration menu depends on the connected Order Management System version and your permissions.

A Data Manager configuration represents one import or export contract. Separate configurations can use different:

• Import or export services

• File formats

• Execution modes

• Templates

For example, order imports, fulfillment updates, and inventory resets can each use a different service and data contract.

Most configurations use a generic HotWax Commerce service after middleware transforms the source data. A native integration can use a service designed for that system’s original payload.

Use Sync only when the service owner has confirmed that the file size and operation are safe. Large synchronous imports can consume resources needed by other work.

Queued imports enter File History in a pending state. The configured bulk-file processing job finds pending files and starts processing them.

When one poller run is already processing the queue, a later scheduled run can stop without starting another processor. Check the run result and active file before treating this behavior as an error.

Use to check the queue and processing job from Job Manager.

Before you change a configuration:

1. Record its current service, execution mode, and template.

2. Confirm every source that uses the configuration.

3. Test the change with approved non-production data.

4. Monitor the resulting file in Job Manager.

See and for the available backend fields and examples.

Mappings translate Shopify locations and order or product values into HotWax Commerce records. Review mappings before starting inventory, product, or order synchronization.

Map inventory locations

1. Open the Company App.

2. Go to Shopify.

3. Select a connection.

4. Open Inventory locations.

5. Select Run facility audit.

6. Review every active Shopify location.

7. Map each location to the matching HotWax facility.

8. Save the changes.

9. Run the audit again and resolve remaining gaps.

Map multiple physical stores to one facility only when the approved inventory design requires it.

This page maps physical Shopify locations to HotWax facilities. Do not map a Shopify aggregate location to a physical facility. Keep the approved aggregate target unassigned, then use to map it to an inventory channel.

1. Open the connection.

2. Select Shipping methods.

3. Review the Shopify shipping option.

4. Select the HotWax shipment method and carrier.

Unmapped shipping methods can prevent imported orders from receiving the intended fulfillment method.

1. Open Payment methods.

2. Review the Shopify payment name.

3. Select the matching HotWax payment method.

4. Add a mapping when no current row exists.

Use a payment method approved by the finance and integration teams.

1. Open Sales channels.

2. Review each Shopify order source.

3. Select the matching HotWax sales channel.

4. Save the mapping.

Sales-channel mappings determine how imported orders are categorized.

1. Open Product types.

2. Review the Shopify product type.

3. Select the matching HotWax product type.

4. Save the mapping.

Review new Shopify product types after catalog changes and map any uncategorized values.

Return to the Shopify connection and review the mapping summaries.

Before activation, confirm:

• Active physical inventory locations are mapped

• Aggregate locations are intentionally unassigned or mapped to an inventory channel

• Shipping methods used by live orders are mapped

• Payment methods used by live orders are mapped

Starter mappings accelerate setup, but they must still be reviewed against the implementation design.

Bulk employee creation is a Data Manager import.

Before you begin

Use the current sample file from the target environment instead of an older local copy.

Import employees

1. Open Data Manager in the OMS.

2. Find the employee import configuration.

3. Download its sample file.

4. Populate the required fields.

5. Upload the file.

6. Review the Data Manager log.

If the import menu lacks the employee import, search Data Manager configurations for IMP_EMPLOYEE.

1. Open the Company App.

2. Go to Users.

3. Search for an imported employee.

4. Confirm the name, employee ID, email, and status.

A successful file upload proves only that Data Manager received the file. Confirm the Data Manager counts and review a selection of imported users.

If the import does not complete or a record is rejected, use the .

The Product Store details page is the canonical reference for brand-level settings. It separates direct Product Store fields from application settings used by order, inventory, routing, fulfillment, and customer workflows.

Change only settings included in the implementation plan. A Product Store setting can affect imported orders and active store operations.

1. Open the Company App.

2. Go to Product Store.

Create an individual user for a named employee. Create a facility login only when a shared location-specific login is part of the approved operating model.

1. Open the Company App.

2. Go to Users.

3. Click the create button.

Add or edit a configuration

If you're creating a new Import configuration to import data from an SFTP location

1. Click the Add button

2. Enter configuration details

If you're editing an existing import or export configuration

• Use the search bar to find the configuration by name or ID.

• Click the Edit icon at the end of the search result.

You may need to view a data manager configuration to either manually import data or to audit data that has been imported either by another user or scheduled SFTP file import job.

1. Click the open link icon beside the service name on the Data Manager Configuration search page.

• This opens the for the selected service.

1. Once a file is done processing, its status will change to Finished.

   If processing finished with error records, download the error records for review. These are usually in JSON or CSV format, with error reasons attached to each record.

2. Click the Log button to view detailed logs related to the service.

3. Use the log to identify any specific failure or irregularity.

Use the Order Sync dashboard to monitor scheduled Shopify order batches, review imports, run approved requests, and investigate failures.

Open the dashboard

1. Open the Company App.

2. Go to Shopify.

3. Select a connection.

4. Open Order Sync.

If the page shows Order Sync needs setup during a standard single-shop launch, begin with of the canonical guide and continue through Chapter 10.

The summary shows:

• Shopify instance and Product Store

• Last completed batch

• Next batch sync

• Orders processed

Click Run now only for an approved unscheduled batch. Investigate a paused job or incomplete mappings before running another batch.

The progress card connects two stages:

1. Shopify order batch request

2. HotWax order import

Open the System Message for request details. Open the Data Manager log for imported record counts and errors.

A completed Shopify request can produce zero actionable changes. In that case, no Data Manager import is required.

The following flow shows when a Shopify request ends by itself and when it continues into a HotWax import.

Use the monitor to review:

• The job that queues Shopify order requests

• Job status and schedule

• Key order dates

• Pipeline activity

When the latest refresh fails, the page can continue to show the last successfully loaded data. Treat the warning as a stale-data condition and retry before concluding that a new run completed.

Use a custom request only for a defined recovery or validation task.

1. Open the custom request area.

2. Search for the Shopify orders.

3. Select the intended orders.

4. Review the selection.

1. Choose the replay option.

2. Enter the approved start time.

3. Review the scope.

4. Submit the request.

Use the smallest time window that contains the affected orders.

1. Click the history action in Track sync progress.

2. Filter by Outcome.

3. Choose Newest first or Oldest first.

History can show a request with no Data Manager import when Shopify returned no actionable order changes.

1. Confirm the Shopify request outcome.

2. Review the related System Message.

3. Review each Data Manager log and its successful and failed record counts.

4. Correct source data in Shopify when the error identifies an order-data problem.

Confirm the latest request time, current job state, and resulting import instead of inferring current success from old history.

A picker must be visible for assignment in the fulfillment workflow and associated with the facility where the work occurs.

Configure an individual picker

1. Open the Company App.

2. Go to Users.

3. Open the user or create a new user.

4. Turn on Show as a picker.

5. Click Add Facilities.

6. Select every facility where the picker can receive work.

7. Save the user.

The assignment dialog lists only pickers associated with that facility.

1. Open the .

2. Open an order or select orders in bulk.

3. Start the picker-assignment action.

4. Search by the picker name, HotWax ID, or external ID.

Bulk picker creation is a Data Manager import, not a native Company task.

1. Open Data Manager in the OMS.

2. Find the Picker import configuration.

3. Download its current sample file.

4. Populate and validate the file.

Use the sample file from the target environment because required columns can change with the import configuration.

1. Open the Company App.

2. Go to Users.

3. Search by user name or ID.

Solr stores searchable product, order, inventory, and other application data in collections. The Maarg Search Admin page lets system administrators prepare those collections and run the index services that load data into them.

Open Search Admin

1. Sign in to Maarg with system administrator access.

2. Open the hamburger menu.

3. Go to Settings > Search Admin. The Admin page opens by default.

4. Confirm that the displayed Instance Name is the instance you intend to manage before running an action.

If the page is not available in the menu, ask a HotWax Commerce administrator to verify your Search Admin access.

The Solr Configuration section identifies the connection used by this Maarg instance:

• Solr Host: The Solr service connected to the current Maarg instance.

• Instance Name: The HotWax Commerce instance whose instance-specific collections you are managing.

• Solr Version: The Solr version used to locate compatible configuration and schema definitions.

When Maarg cannot reach Solr, the page displays Solr is not available and disables configset, collection, and index actions. Record the connection error and the three configuration values, then contact the HotWax Commerce technical team. Do not continue with index setup until the connection is restored.

A configset supplies the Solr configuration used to create a collection. The Configset Operations table shows every configset deployed with the application and how many active collections use it.

• Click Upload on one row to upload or overwrite that configset in Solr.

• Click Upload All Configsets during initial setup or a planned upgrade to upload all deployed configsets. This action overwrites configsets that already exist.

• Click Delete only when the configset is no longer needed and no collection uses it. Solr rejects deletion when an active collection still uses the configset.

Uploading a configset does not create a collection or index application data. Complete the collection and index operations that follow.

A collection stores indexed documents. The Collection Operations table shows the live state of each collection declared by the application:

• Status: Whether the collection is active or missing.

• Documents: The number of indexed documents.

• Index Size: The storage used by the index.

• App Fields: The number of application fields from the deployed schema that are present in Solr.

Use the row actions as follows:

• If the collection is missing, upload its configset and then click Create Collection.

• During initial setup, click Create All Collections to create every missing collection declared by the application. Existing collections are skipped.

• For an active collection, click View Fields to compare the deployed schema with the live Solr schema.

Click View Fields for a collection to open its Field Comparison section. Use the summary and tables to interpret the result:

• Missing from Solr: Fields declared by the deployed application schema that are not present in the live collection. Use Add Missing Fields from the collection row to apply them.

• Additional in Solr: Live fields that are not declared by the deployed application schema. These are informational and are not removed by Add Missing Fields.

• All Schema Fields: The deployed definitions for regular fields, dynamic fields, and copy-field rules, including their source document type and field settings.

After adding fields, reopen View Fields and confirm that Missing from Solr is 0.

The Index Operations table is generated from the deployed schema. Each row identifies a Collection, Doc Type, and Index Service, so the available rows can differ by HotWax Commerce implementation and version.

1. Confirm that Solr is available and the target collection is active.

2. Locate the document type you want to index.

3. Click Run Index.

4. Review the service parameters in the dialog. Use the narrowest supported parameters when repairing a specific record or subset.

1. Verify the Solr Host, Instance Name, and Solr Version.

2. Click Upload All Configsets.

3. Click Create All Collections

1. Upload the changed configset, if the release includes a configset change.

2. Open View Fields for each affected collection.

3. Click Add Missing Fields when the comparison reports missing fields.

1. Confirm that Solr is available and the collection status is Active.

2. Use View Fields to check for a schema mismatch.

3. Add missing fields, if present.

A scheduled file import can fail when the service-job parameter points to the wrong Data Manager configuration or when the configured secure file transfer protocol (SFTP) path does not contain the expected file.

Check the configuration identifier

1. Open Run history in Job Manager.

2. Find the failed import job.

3. Expand Parameters and Errors.

4. Record the configuration identifier used by the run.

5. Open Settings > Data Manager Configurations in the Order Management System.

6. Find the configuration and compare its identifier.

Correct the job parameter only when the failed run used the wrong configuration.

See .

1. Open the Data Manager configuration.

2. Record the configured import path.

3. Ask an authorized integration administrator to confirm that the expected file exists at that path.

4. Compare file name, path, archive behavior, and timestamps.

Do not copy passwords, private keys, or connection secrets into issues, chat, documentation, or screenshots.

1. Run the import through its normal source or schedule.

2. Open File history in Job Manager.

3. Find the resulting file.

4. Review its status, timeline, and errors.

Do not upload a production file as a configuration test unless the service owner has approved the data and outcome.

Use this page after a Shopify shop is connected to HotWax Commerce. It covers reviewing and maintaining an existing connection, not initial setup.

For a new connection, follow Set up HotWax Commerce with Shopify.

Find a connection

1. Open the Company App.

2. Go to Shopify.

3. Search for the shop when needed.

4. Filter the list by connection status.

5. Select a connection.

The connection page groups configuration into three areas.

Product Sync and Inventory sync appear with the products and inventory workflow when available for the connection.

1. Open the connection.

2. Select Instance details.

3. Review the shop name, Shopify domain, and timezone.

4. Review the refund-upload setting.

The Shopify domain identifies the remote shop. Confirm it before changing another connection setting.

1. Open the connection.

2. Select Product Store.

3. Confirm the Product Store that owns the Shopify shop.

4. Change it only when the implementation owner approves the downstream catalog, inventory, and order impact.

A Shopify shop can be linked to only one Product Store.

Use the credentials page only when the implementation team provides a current Shopify credential change.

1. Open API credentials.

2. Confirm the Shopify shop.

3. Enter the approved credential values.

4. Save the change.

Keep credentials out of tickets, screenshots, and documentation.

1. Open Access scopes.

2. Under Connection access, confirm the OMS-side access level required by the integration.

3. For inventory publication, confirm SHOP_RW_ACCESS. Do not use SHOP_READ_WRITE_ACCESS; it has the same description but does not satisfy the current service gate.

Use these references to operate an existing connection:

Exclude the development-only Debug area from operator workflows.

Use the Product sync dashboard in the Company App to monitor scheduled imports, review the current pipeline, run targeted sync requests, and troubleshoot failed products.

This guide covers day-to-day product sync operations after setup. To connect a new shop, use Chapter 4 of Set up HotWax Commerce with Shopify. To move a shop from the legacy pipeline, use Upgrade Shopify product sync.

Open the product sync dashboard

1. Open the Company App from the HotWax Commerce Launchpad.

2. Select Shopify from the menu.

3. Select the Shopify connection that you want to monitor.

4. Select the active Product sync card.

The card summarizes records processed in the last completed import, unsynced Shopify events, and the latest pipeline status. If the connection shows Setup new product sync, complete the . If it shows Upgrade to new product sync or Disable old product sync, follow the .

The dashboard brings the current run, scheduled jobs, pipeline health, and custom requests into one view.

The Summary card shows:

• The last completed sync and its relative time

• The number of updates processed in the last sync

• The next scheduled sync or a Paused status

• The number of unsynced Shopify updates

Select the lightning action to run the recurring sync job now. The app asks for confirmation because stopping an active job run is unavailable.

Open the overflow menu to select Reschedule, Pause, or Resume. Select the Next sync time row to review the job schedule, run the job, change its schedule, and view its audit history.

Select Un-synced updates to review Shopify products waiting to be imported. Select one or more products, then select Sync selected products to import them on demand.

The Track sync progress card follows the latest run through the complete pipeline:

Select an available stage to open its details.

The System Message modal shows:

• The system message ID and current status

• Why the run is waiting and which job performs the next step

• The next scheduled time for that job, when available

• A Send now, Poll now

Use the message ID when sharing a specific run with the technical team. If a message remains Produced, check the listed Send update request schedule or use Send now. If it remains Sent, check when Import completed requests runs or use Poll now. A missing bulk operation ID means that Shopify hasn't accepted the request yet. Open Error Text when the message reaches an error state.

The Bulk Operation modal shows the Shopify bulk operation ID and its current status. It also shows the status reported for the current sync run, or Pending when the app hasn't received one yet.

Use the bulk operation ID to identify the request in Shopify or when escalating a run that remains active for an unusual amount of time. If the system message is still Produced and no bulk operation ID exists, investigate the send stage instead of Shopify processing. After Shopify completes the operation, investigate Import completed requests when the HotWax import doesn't begin.

The Data Manager Log modal loads the import log and shows:

• Log ID and status

• Total record count

• Successful record count

• Failed record count

Use the log ID when sharing an import with the technical team. Compare the total, successful, and failed counts to determine whether the whole file failed or only particular products need correction. When failed records are present, continue to Parsed error details or download the failed-record file from sync history.

Select the history icon on the card to open .

The Product sync jobs card shows the jobs and webhook that move requests through the pipeline:

• Queue update requests creates product sync requests on the shop's schedule.

• Send update request sends produced requests to Shopify.

• Import completed requests checks completed operations and starts the HotWax import.

Select Queue update requests, Send update request, or Import completed requests to open the service-job modal. Each modal shows the following information and controls:

Use the refresh action to reload the job details. When you change Active or Schedule, use the save action. Closing or refreshing with unsaved changes displays a discard confirmation.

The most useful checks depend on the job:

• Queue update requests is the shop-specific job. In Parameters, verify shopId, productStoreIds, and shopifyProductIdentifier when available. These values confirm which Shopify shop, HotWax product store, and internal name mapping the job uses. Check its active state, schedule, and recent output when Shopify changes aren't creating product sync requests.

• Send update request sends produced system messages to Shopify. Check its active state, next run, and recent output when the current system message remains

A pause icon means that the corresponding job is paused. Resume paused jobs that the scheduled pipeline requires.

The Pipeline card shows pending update requests, the current Shopify request, update files waiting for import, and error records from the last 24 hours. A growing count usually points to a paused job, a request still waiting to finish, or import errors that need review.

Recently synced product updates lists products processed by recent sync runs. Use the search field to find a product by internal name. Each product card can show:

• Product title, variant title, SKU, Shopify ID, and sync time

• A link to the product in Shopify

• A summary of changed fields

• A Changes section with field-level values

An empty change list means field-level details are unavailable. The product may still have synced successfully.

Use the Custom request card when you need a result before the next scheduled run.

1. Select Sync specific products.

2. Search by SKU, product name, or Shopify ID.

3. Select the products to import.

4. Select Sync selected products

Use this option after correcting one or more products in Shopify or when a small set of updates needs immediate processing.

1. Select Replay sync from a certain time.

2. Set Sync updates from to the start of the period that must be processed again.

3. Select Start replay sync.

Replay changes the last-sync time so that Shopify updates from the selected time are imported again. Use the narrowest practical time range to avoid processing unrelated updates.

1. Select Re-sync entire catalog.

2. Review the current Shopify product and variant counts.

3. Select Start full catalog re-sync.

This request imports every product that currently exists in Shopify. It can take a long time for a large catalog.

Parsed error details shows failed objects from recent Data Manager logs. Each card includes the product title or handle, Shopify product ID, and the parsed error message.

1. Search by product ID, name, or handle.

2. Select View details to review the full error record.

3. Correct the source data or configuration that caused the error.

4. Select Retry

Use the refresh action to reload the error list after another import finishes. When a failed record lacks a Shopify product ID, direct retry is unavailable. Use the error details to locate the source product or ask the technical team for help.

Select the history icon in Track sync progress to open Product sync history.

Use these filters to find a run:

• System message status: Produced, Sent, Received, Consumed, Confirmed, or Error

• Sort

Expand a run to review the system message, Shopify bulk operation, and HotWax bulk import.

• Select Message text or Error details to inspect the system message.

• Select View query to inspect the Shopify query when available.

• Select the total record count to download the raw Shopify import file when available.

A Produced message is waiting for the send job. A missing Shopify bulk operation ID can be normal until Shopify accepts the request. A skipped HotWax import can be normal when Shopify returns no updates.

Contact the technical team when required artifacts are missing, a pipeline job continues to fail, or the same product fails again after you correct its source data.

HotWax Commerce’s Fulfillment App can be accessed by users with FULFILLMENT_APP_VIEW permission. However, actions like rejecting orders or marking items as shipped need specific permissions.

Below is a list of all the actions available in the Fulfillment App, along with the specific permissions needed to perform them.

Open Orders tab

Manage All Fulfillment Operations

Use the Inventory sync dashboard in the Company App to monitor inventory published from HotWax Commerce to Shopify. The dashboard separates physical-location quantity on hand from aggregate-channel available-to-promise inventory, so you can investigate the correct path before changing a schedule or running a reset.

This guide covers outbound inventory updates after a Shopify connection is set up. It does not import starting inventory from Shopify. For the one-time inbound quantity-on-hand seed, follow Chapter 8 of Set up HotWax Commerce with Shopify.

Understand the two inventory paths

HotWax Commerce can publish inventory to Shopify in two ways:

Quantity on hand (QOH) is the physical count at a location. Available-to-promise (ATP) is the quantity available for new orders after HotWax Commerce applies reservations and sourcing rules. Do not use a physical QOH reset to repair an aggregate ATP target, or an aggregate ATP reset to repair a physical-location target.

See for the rules that determine which facilities contribute to a channel.

1. Open the Company App from the HotWax Commerce Launchpad.

2. Select Shopify from the menu.

3. Select the Shopify connection that you want to monitor.

4. Select Inventory sync

Before you rely on the dashboard, open Access scopes on the connection and confirm both write gates:

• Under Connection access, confirm SHOP_RW_ACCESS. Do not select SHOP_READ_WRITE_ACCESS; it has the same description but does not satisfy the current service gate.

• Under Granted OAuth scopes, refresh the Shopify scopes and confirm write_inventory for the approved connection profile.

Resolve either missing gate through the approved Shopify connection flow before you publish or reset inventory.

Start with the queue and job-health cards. They answer two different questions: what is waiting, and what should move it.

As of August 24, 2026, the screenshots and event-pipeline terminology in this guide preview the unreleased feat/inventory-event-pipeline-view UI at commit 672694b. This commit is not on Company main or in a tagged release, and the preview still reports package version 2.2.1. Do not use the version label alone to identify this UI. Until a deployed release contains it, follow the older Company and Job Manager surfaces described in the release boundary below.

The screenshots use fictional demo data; their shop, channel, location, event, batch, and job identifiers do not describe a live retailer. In the overview, Needs attention reflects the intentionally paused manual discard job; assess automatic pipeline health from the individual job rows.

The Aggregate event queue card shows:

• Aggregate events pending batching: Calculated adjustments that are not assigned to a System Message

• Batches pending delivery: System Messages that are waiting to send, retrying, or in an error state

• Next batch send: The next active publisher schedule

The pending-event count represents inventory event-detail rows. One receipt, reservation, or configuration change can create rows for multiple channels or Shopify inventory items, so do not interpret this number as a count of business events or products.

Next batch send is the earliest active channel-publisher run that the dashboard can find. It does not confirm that every channel has a publisher, that the produced-message sender is active, or that Shopify has received a batch.

Select an event or batch row to open inventory event history.

Shared sync jobs contains schedules that serve the connection or every Shopify inventory channel on the OMS. Each channel card contains the two schedules that belong only to that channel. Both surfaces show a configured job as Active or Paused, and show Not configured when the required job is missing.

The jobs displayed depend on the installed Company and Shopify connector releases. Process effective-dated inventory changes and Purge old inventory events are connector-seeded jobs. If either is missing, treat it as a deployment gap. Do not copy a job definition from another instance.

Inspect every shared and channel-owned row before you use the Shared sync jobs rollup as a health verdict. The rollup includes the jobs inside channel cards, even though it is displayed on the shared card. A manual recovery job can be intentionally paused and have no schedule while the automatic publication pipeline remains healthy.

Select a configured job from its shared or channel row to review its internal name, service, active state, schedule, parameters, recent runs, and edit history. A row can summarize multiple matching jobs and open only one of them. Use Job Manager to check for duplicate or overlapping schedules before you activate or reschedule a job. Select Run now only after you confirm the job scope and verify that an earlier run is not active.

A job's next-run line can show a countdown and timestamp. If the cached next-run timestamp is older than a more recent run, Company shows the cron cadence instead of reporting a false overdue state. Next run not yet recalculated means that the schedule exists but the cache has no dependable next timestamp. No active schedule means that Company found no unpaused matching job with a cached next-execution timestamp; inspect the job's paused state and cron expression before you conclude that it is unscheduled.

A completed run means that the job has an end time and did not report an error. It does not prove that Shopify now matches HotWax Commerce. After a reset or recovery run, compare representative item quantities at the affected Shopify target.

If the dashboard offers Set up, the app creates the missing job in a paused state. Open the new job and verify its parameters and schedule. Activate only jobs approved for scheduled execution. Keep Discard unbatched events paused and unscheduled.

Some Company versions allow supported job parameters to be edited in the job modal. Keep inventoryChannelId unchanged for a channel publisher or reset job because that value defines which channel the job belongs to.

The channel-card job placement and the four-stage event pipeline are an unreleased preview at 672694b. Older released deployments can show the channel jobs in a single Inventory sync jobs card and provide separate All events and Grouped by batch history views. Use Job Manager and the controls visible in that deployed Company build when the newer surfaces are absent. Replace this commit boundary with the released Company version after the feature ships.

Keep the publish_PendingShopifyInventoryAdjustments template paused. Each inventory channel needs its own cloned publisher job. Before you activate a clone, confirm:

• inventoryChannelId identifies the intended channel.

• maxChangeCount is 100, unless the implementation plan specifies another tested batch size.

• staleSendingMinutes is 60

A newly created clone is paused. Activate it only after its channel, parameters, and schedule are correct; do not activate the template itself.

When the sender's systemMessageTypeIds value is blank, that job sends all supported System Message types. It is a shared sender, not an inventory-only sender. Do not change or replace a shared sender as an inventory recovery action.

Some Company versions can show the sender as both Active and Set up: an active shared sender exists, but a dedicated inventory sender does not. A dedicated inventory sender is created paused and should use:

• A five-minute schedule

• systemMessageTypeIds set to ShopifyInventoryAdjustment

• mode set to sync

Review the shared delivery design with the deployment owner before activating a dedicated sender, so the same messages are not targeted by unintended schedules.

App-created reset jobs start paused. Use these defaults to audit a newly created job; preserve an approved deployment-specific schedule when it intentionally differs.

• The physical QOH reset runs hourly by default. Its parameters must include systemMessageTypeId=ResetInventoryQoh, the selected shop's systemMessageRemoteId, and runAsBatch=true. Together, these values define its Shopify connection scope.

• Each aggregate ATP reset runs every four hours by default. Its protected inventoryChannelId must identify exactly one inventory channel.

Do not copy a physical reset between connections or an aggregate reset between channels by changing only the job name. Verify the scope parameters first.

Discard unbatched events is one OMS-wide manual recovery job that acts on one selected channel per run. Keep it paused and without a schedule. Never activate or schedule it.

When obsolete unbatched events must be removed:

1. Open the discard job and select the intended inventoryChannelId.

2. Enter and review the reason.

3. Select Save.

4. After the modal closes, reopen the job and verify the stored channel and reason.

The lower dashboard sections show:

• Recent full physical-location QOH reset runs

• Recent full aggregate ATP reset runs

• Aggregate event batches, their delivery states, publish reasons, and summed change entries

Each run card shows its run identifier, start time, parameters, scope, result, and whether the job reported an error. Select View all runs to search one job's history by run, service, user, parameters, result, and status.

The job modal previews only the five most recent runs and ten edit-history records. Use View all runs when the required execution is not in that preview.

The job-run page loads at most the 500 most recent runs. When it reaches that limit, it displays a warning rather than presenting the results as complete history.

An aggregate inventory channel maps one channel facility group to one Shopify location. Eligible inventory from the facilities in the group contributes to that target after the channel's brokering, safety-stock, threshold, and demand rules are applied.

Feeding this channel counts effective facility-group members by facility type. Delivered in 24h counts cached ledger-detail rows that were created in the last 24 hours and currently have a sent System Message. It is not a count of deliveries, units, products, or batches; an older row delivered today is excluded. Treat this value as a recent operational signal rather than a complete throughput total.

Before you begin:

• Create and review the channel facility group in Sourcing > Channels.

• Confirm the facilities that belong to the group.

• Create or select a Shopify location intended only for aggregate inventory.

Follow these steps:

1. Open the Inventory sync dashboard.

2. Select Set up channel.

3. Select a facility group. The app lists only groups of type CHANNEL_FAC_GROUP and shows their store, warehouse, configuration, and other facility counts.

The location list excludes locations that already back a physical HotWax facility or another active inventory channel. A location mapped to the _NA_ placeholder can appear as Suggested because it is not assigned to a physical facility. Use _NA_ only for an intentionally unassigned aggregate target, not as the mapping for a real store or warehouse.

After the channel is created, the app attempts to create its aggregate reset and event-publisher jobs and the connection's physical reset job. These jobs are created paused.

Select a channel from the Inventory channels section to manage it.

The Shopify shop and facility group are fixed because they define the channel's identity. You can update the description and choose another eligible aggregate location. Open Reset aggregate ATP on the channel card to review or change that channel's full-reset schedule.

1. Select the channel.

2. Select the new Shopify aggregate location.

3. Confirm that no other active inventory channel uses the new target. The edit dialog does not exclude every target claimed by another channel.

4. Review the warning.

The Company warning states that inventory placed by the channel should be cleared from the old target. Saving the edit records the new target, while the connector performs the inventory clearing. Verify both Shopify locations after the save and reset. If the old target remains stocked, do not reuse it; record the channel and location identifiers and escalate the failed clear. Incremental events alone do not seed the complete quantity at the new location.

1. Open the channel's publisher and aggregate reset jobs in Company or Job Manager and record their internal job names.

2. Pause the aggregate reset job and save the change. Keep the channel publisher and produced-message sender active so they can deliver the clearing adjustment created by expiration.

3. Verify that the aggregate reset has no active run and that the publisher is not currently running.

4. Review event history for the channel. Resolve pre-existing Waiting

Expiration is intended to stop aggregation into the target and clear the inventory that the channel placed there. Verify the Shopify target after expiration. HotWax Commerce retains the mapping so historical events remain attributable to the expired channel.

Expiration removes the channel from the active channel rows, but the Company page does not show it pausing or deleting the channel's publisher and reset jobs. If the clearing adjustment does not appear or the Shopify target is not zero, keep the location out of use, record the channel and location identifiers, and escalate before pausing the publisher or assigning the location elsewhere. If the installed connector uses a different approved decommission path, follow that release-specific runbook instead.

The dashboard contains three controls with different scopes. Review the scope and recovery action before changing one.

When you enable Inventory channel event updates, restart every OMS node so that Moqui registers the real-time feed. When you switch it to manual, new real-time events can continue for up to 15 minutes while the cached feed configuration expires.

Event sources determine which OMS changes create aggregate inventory events. The supported sources cover:

• Shipment receipts

• Point-of-sale item issuances

• Physical inventory changes and external inventory resets

• Reservation creation and release

If a source displays Not loaded on this OMS, the connector's seed data is missing. The toggle cannot create the missing source. Record the source name and ask the deployment owner to load the matching connector seed data.

Open inventory event history from an aggregate queue row or select Event history in the batch section.

The page presents one Inventory event pipeline in the order that the publisher acts. Use search and the available filters to decide which groups, batches, and rows remain visible by:

• Event type and source record

• Resolved product name or SKU, when available

• Shopify inventory item identifier

• Shopify location

The Status filter applies to the inventory-event ledger lifecycle. It does not filter System Message delivery states such as Produced, Sending, Error, or Sent.

The shown badge counts matching ledger rows. When one event matches inside a waiting group or batch, that card continues to show the complete publisher boundary, including its full event count and summed change entries. Do not interpret those totals as a subtotal of only the matching rows.

The ledger's remote identity is the Shopify inventory item. The page also tries to resolve the OMS product and originating business record, such as an order, receipt, cycle count, reset, reservation, or point-of-sale movement. Treat an unresolved enrichment as missing context, not as proof that the source record does not exist.

The following flow separates the inventory-event ledger lifecycle from System Message delivery and recovery.

Within the ledger, lifecycle and delivery are separate state machines:

Open an event to review its source record, resolved originating artifact, actor or note when available, product and SKU, Shopify inventory item, channel, effective Shopify location, publish reason, batch delivery, and ATP calculation. The raw ledger reference remains available when the human-readable source does not contain it.

Waiting to batch puts the oldest group first. By default, a publisher group is scoped to one channel, Shopify inventory item, and event type.

In preview commit 672694b, the page applies the first nonblank groupByFields value that it finds among the cached channel publishers to every waiting channel. The displayed grouping matches actual publication only when the channel publishers use the same grouping fields. Compare groupByFields on every affected channel publisher in Company or Job Manager before you rely on the cards for a mixed-channel audit.

For each group, verify:

• Publishes under: The Shopify inventory-adjustment reason. An unmapped event type or a group containing mixed event types falls back to correction; resolve an unexpected fallback before it freezes into a System Message.

• Change entries Shopify will receive: Events for the same Shopify inventory item and effective location are summed into the delta that Shopify receives.

• Outcome warnings: A zero sum settles as No change

If the page warns that batches can mix event types, the publisher's grouping configuration omits event type. Such a mixed batch must use correction because no more specific Shopify reason describes every event in it.

The history page is an operational monitor, not a permanent archive. It initially loads a recent set plus all pending and unresolved rows, then adds new updates; it is neither a fixed 500-record report nor complete history. The UI labels the settled stage as a five-day tail, but the client does not enforce an age cutoff or remove already cached rows when the backend purge runs. Older settled rows can remain visible until the app cache is cleared, normally at logout or an identity change. Use backend records when an investigation requires a complete or authoritative time window.

1. Find the batch under In flight and failed.

2. Select Events on the failed batch.

3. Record the System Message identifier, target, status, and delivery errors.

The app resends the same frozen payload and idempotency key. Review the resulting Shopify and System Message states before another retry. Repeated retries without correcting the cause still create noise and delay recovery.

The batch dialog fetches up to 50 delivery errors and can retain that cached set after the dialog or page is reopened. Use backend System Message error records to inspect the newest attempt, more than 50 errors, or older error history.

Select Message text when the technical team needs the stored System Message payload. If the dialog says that the payload is still loading, refresh or reopen it before treating the displayed content as exact. Keep credentials and customer data out of screenshots and tickets.

1. Open the row under Quarantined.

2. Record its source record, product, inventory item, effective Shopify location, and ATP calculation.

3. Correct the invalid source data or configuration that produced the terminal result.

4. Use the approved business workflow to record a new inventory event; the quarantined row itself is never batched again.

1. Confirm that the Shopify location maps to the intended HotWax facility.

2. Confirm that Real-time inventory push for this shop is enabled.

3. Review Reset physical location QOH, including its active state, schedule, parameters, and latest run.

1. Confirm that the inventory channel maps the intended facility group to the intended Shopify target.

2. Review the channel's facility membership and sourcing rules.

3. Confirm that Inventory channel event updates and the relevant event source are active.

4. Check the oldest waiting group and the publisher row inside the channel card.

1. Filter history to Waiting and the affected channel.

2. Find the oldest group in Waiting to batch and record its age.

3. Review Publish and send event batches on the channel card, including its active state, next run, and recent runs.

1. Find the batch under In flight and failed and record its System Message identifier.

2. Select Events to review its delivery errors and contributing events, and use Message text when the stored payload is required.

3. Check the inventory-batch sender when it is displayed, or the deployed System Message sender in Job Manager.

1. Open the quarantined event and record its source, product, target, delta, and calculation.

2. Correct the source row or configuration; the terminal ledger row will not retry.

3. Record a new event through the approved business workflow.

4. Run a full aggregate ATP reset when the affected target may remain out of sync.

1. Identify the missing business event, such as receipt, reservation, point-of-sale issuance, or configuration change.

2. Find the matching event source.

3. Distinguish off from Not loaded on this OMS.

Contact the technical team with the Shopify connection, inventory channel, target location, event type, source record, Shopify inventory item, System Message identifier, job-run identifier, timestamps, and the first recorded error when the same discrepancy returns after reconciliation.