HPK Agent Warehouse Guide

Updated: 2026-08-06

1. What this page covers

This page only covers rules that are specific to HPK. It does not repeat the generic agent warehouse configuration and task page operations.

Read this page first if you're dealing with:

• What capabilities HPK currently supports;
• How to interpret HPK inventory quantities;
• Which outbound flows go through the agent warehouse for HPK, and which don't;
• Where to look first when an HPK task stays pending for a long time, a cancellation fails, or inventory doesn't sync.

If you haven't finished configuring the system, warehouse, or channel mapping yet, read Agent Warehouse System first. If you already have a failing task and need to check status and retries, read Sync Tasks.

2. Configuration

2.1 Add an HPK System

Menu path: GWMS > Agent Warehouse > Agent Warehouse System

1. Click 【Add】
2. Fill in 【System Name】
3. Select "HPK (Hipacking)" for 【System Type】
4. Enter the connection details provided by HPK:
   • API endpoint
   • Login account
   • Login password
   • Version number (enter 5)
5. Click 【OK】

Test environment URL: http://test.hipacking.cn

2.2 Configure Warehouse Mapping (Important)

Menu path: GWMS > Agent Warehouse > Agent Warehouse System > Warehouse

All 4 fields are required:

1. Agent warehouse code
2. GWMS warehouse code
3. Virtual Shelving Location (for HPK qualified goods)
4. Defective Product Location (for HPK defective goods)

❗ If dedicated locations are not configured:

• Inbound orders can be received but not put away
• Inventory sync cannot be triggered

2.3 HPK Inventory Quantities

HPK returns two types of inventory:

• Available inventory: quantity that can be allocated to outbound orders
• Locked inventory: quantity already allocated but not yet shipped

Important: Total inventory = Available + Locked

❌ Wrong: Looking at available inventory only ✅ Correct: Available + Locked = Total inventory

Example:

• HPK shows: Available 80, Locked 20
• Actual total inventory: 100 (not 80)

3. Current Scope

3.1 Inbound

1. Create an inbound order in GWMS
2. The system automatically pushes it to HPK
3. Check task status on Sync Tasks
4. Once HPK finishes processing, GWMS automatically receives and puts away the goods

Notes:

• After the push, wait for HPK to finish processing
• "Waiting" doesn't only mean HPK is currently processing — it can also mean the task has already moved into the next automatic polling cycle
• Putaway only fails to happen when dedicated locations are missing

3.2 Serial Number Sync

HPK currently supports serial-number-related flows, but they are not a separate new task type — they run attached to the main inbound or outbound flow.

Currently supported:

• Once an inbound order is created successfully, the system automatically pushes the local serial numbers already bound to this order to HPK.
• If local inbound serial numbers are later added, changed, or removed, the system syncs the change to HPK asynchronously after the transaction commits.
• When HPK returns a final inbound result, the system parses serial numbers out of the response and writes them back to GWMS local inbound serial number records.
• When HPK returns a completed outbound result, the system parses serial numbers out of the response and writes them back to GWMS local outbound serial number records.
• During sync, the system resolves the corresponding HPK product via SKU mapping before running serial number entry, query, update, or local write-back.

Important boundaries:

• "Pushing to HPK" and "pulling from HPK back to GWMS" are two separate directions — don't mix them together when troubleshooting.
• In the current code, a failed inbound serial number write-back does not fail the inbound main flow — the system keeps the main flow's result and waits for a later poll to fill it in.
• In the current code, a failed outbound serial number write-back does not fail the outbound main flow either — the outbound main flow's result is kept as-is.

How to troubleshoot:

1. First confirm whether this order has actually gone through the HPK agent warehouse flow at all.
2. If you're checking "did the local side push to HPK", go to Logs and look at the serial number entry, query, and update requests/responses.
3. If you're checking "did HPK write back to GWMS", go to Logs and check whether the inbound or outbound status query response actually included serial numbers.
4. If the logs already show success but the business still looks off, go back to Sync Tasks and cross-reference the inbound or outbound task status to see if there's still a main-flow issue.

HPK serial number boundary quick reference:

Question you want answered	Actual direction	Check here first	Current code boundary
Did the local inbound serial number get pushed to HPK	GWMS -> HPK	Logs	Only the inbound serial number push exists — no separate task page
Did HPK's inbound result bring the serial number back to GWMS	HPK -> GWMS inbound write-back	Logs first, then Sync Tasks	A failed write-back doesn't directly break the inbound main flow
Did HPK's outbound result bring the serial number back to GWMS	HPK -> GWMS outbound write-back	Logs first, then Sync Tasks	A failed write-back doesn't directly break the outbound main flow

3.3 Outbound

In the current code, HPK outbound first splits by business type:

• Drop shipping: the current agent warehouse main flow supports push, status query, and cancel confirmation.
• Transfer staging: this does not go through the agent warehouse push flow at all — cancellation does not send a cancel request to HPK either.

For drop shipping outbound:

1. GWMS creates the outbound order.
2. The system automatically pushes it to HPK.
3. The system creates a task and polls HPK's processing status on a schedule.
4. Once HPK completes the order, GWMS advances the local outbound status.
5. If HPK's outbound result for this order includes serial numbers, the system also tries to write them back to GWMS local outbound serial number records.

For transfer staging outbound:

• Don't assume it will complete an HPK push through the current agent warehouse task page;
• Don't assume a cancel request will be sent to HPK either;
• For this type of order, first confirm whether the current business scenario has actually been onboarded to the agent warehouse flow.

Additional context:

• Outbound serial numbers currently mainly work as "HPK brings it back in the outbound result, then GWMS lands it locally" — not as "GWMS actively pushes to HPK".
• If outbound serial number write-back fails, the current code does not change the outbound main flow's result to failed because of it — you still need to look at task status and logs together.

3.4 Inventory Sync

Triggers:

• Click 【Sync Inventory】 on the warehouse mapping page
• The system also runs it automatically every 12 hours

What it does:

1. Completes any unfinished inbound/outbound tasks for the same warehouse first
2. Pulls an inventory snapshot from HPK
3. Automatically corrects local inventory discrepancies
4. Saves the inventory snapshot

View results: Go to Sync Tasks to see inventory sync task details.

Notes:

• Only the virtual shelving location and defective product location are corrected
• Inventory sync itself doesn't rely on polling, but the business pre-processing step before it has a budget on count and duration — it doesn't have to wait for every business task to finish first

4. Common Issues

4.1 "Virtual Shelving Location not configured"

Cause: Warehouse mapping is incomplete

Resolution:

1. Go to Agent Warehouse System and check warehouse mapping
2. Verify that both the virtual shelving location and defective product location are configured
3. Fill in any missing configuration

4.2 "Customer account not open, cannot receive"

Cause: Local customer data does not meet receiving requirements

Resolution:

1. Check the error details on Sync Tasks
2. Verify the customer's account status
3. Check whether the customer is bound to the correct warehouse
4. After fixing the issue, click 【Sync Now】

4.3 "System configuration error"

Cause: Incorrect system type or configuration

Resolution:

1. Confirm that HPK is selected for 【System Type】
2. Confirm that warehouse mapping is set up
3. Verify the API endpoint, account, and password
4. Check error details on Logs

4.4 "SKU sync failed"

Cause: GSKU master data is incomplete

Resolution:

1. Go to the 【SKU】 page on the agent warehouse system
2. Check required GSKU fields (name, specification, weight, etc.)
3. After completing the data, click 【Resync】

4.5 Serial numbers aren't syncing to HPK

Common causes:

• The current warehouse route hasn't enabled inbound serial number sync capability;
• This inbound order hasn't been successfully created at HPK yet;
• SKU mapping is missing, so the system can't resolve the corresponding HPK product;
• The local serial number state has since changed, so the system judged this event as stale and skipped it;
• The HPK API returned a failure or an error.

Resolution:

1. First confirm this warehouse and system actually go through the HPK agent warehouse flow.
2. Confirm the inbound order has been pushed successfully and has an HPK order number.
3. Check Logs for the serial number entry, query, and update requests/responses.
4. Check whether SKU mapping is complete; fill in any missing mapping and re-trigger the relevant business action if needed.

4.6 HPK serial numbers aren't writing back to GWMS

Common causes:

• HPK's inbound or outbound status response simply didn't include serial numbers;
• The response included serial numbers, but SKU mapping didn't match a GWMS product;
• The local main flow has already completed, but this particular serial number write-back failed to parse or save;
• This response hasn't been polled yet — a later poll will bring the serial numbers back.

Resolution:

1. Check Logs to confirm whether HPK's inbound or outbound status response actually included serial numbers.
2. Confirm the SKU in the response matches the correct GWMS product mapping.
3. Then check Sync Tasks to confirm whether the main flow has completed, and whether there's still a chance for a later poll.
4. If the main flow has completed but the serial number is still missing, keep troubleshooting via logs and mapping — don't just look at the task status color.

4.7 Task stays in waiting status

Common causes:

• HPK hasn't reached a final status yet;
• The task has already moved into the next automatic polling cycle;
• The execution summary already shows an error, but it hasn't been handled manually yet;
• Mapping, system configuration, or master data issues haven't been fixed yet.

Resolution:

1. Check 【Execution Summary】 and 【Next Run Time】 on Sync Tasks first.
2. If the summary clearly points to a configuration or data issue, fix it first — don't just keep clicking 【Sync Now】.
3. If there's no obvious error, check HPK's actual response on Logs.
4. Contact HPK to confirm the order's real processing status if necessary.

4.8 What happens locally after a cancellation fails

For HPK, don't treat "local cancel click succeeded" and "HPK side also cancelled successfully" as the same thing.

• For business that currently goes through the agent warehouse cancel flow, if HPK's cancel doesn't go through, this cancellation does not end as a success — you need to find the cause before retrying.
• For business that currently doesn't go through the agent warehouse cancel flow, such as transfer staging at this stage, don't assume HPK receives a cancel request.

5. Related Pages

• Configure the HPK system: Agent Warehouse System
• Check task status: Sync Tasks
• View request details: Logs