REST API v4 (WMS)

The REST API v4 (WMS) allows you to programmatically manage warehouse operations in your ShipEdge Warehouse Management System. This API provides endpoints for inventory recounts, order weight updates, shipment management, and bin information retrieval.

Quick Start

Get your Username and Master API Key from System Config > Preferences > Operations > Shipedge master API Key in your WMS account. Use these credentials in all API requests.

Why Use REST API v4 (WMS)?

Automate Inventory Operations

Perform inventory recounts and corrections programmatically without manual warehouse operations.

Update Order Weights

Update order weights automatically after weighing packages, integrating with scale systems.

Manage Shipments

Revert shipments to pending status when corrections are needed before shipping.

Access Bin Information

Retrieve detailed bin information for products to support warehouse operations and reporting.

---

Base URL

All WMS API endpoints use this base URL:

https://your-instance.shipedge.com/apirest/v4/wms/

Replace your-instance.shipedge.com with your actual ShipEdge instance URL.

---

Authentication

REST API v4 (WMS) requires authentication via HTTP headers in every request.

Required Headers

userName: [Your warehouse username]
Key: [Your master API key]

Getting Your Credentials

1. Log in to your ShipEdge WMS account

   Access your Warehouse Management System account through the web interface.

2. Navigate to System Config

   Go to System Config in the main menu.

3. Open Preferences

   Click on Preferences in the System Config menu.

4. Go to Operations section

   Navigate to the Operations tab or section.

5. Find Master API Key

   Look for Shipedge master API Key field. If no key exists, click Generate an API Key to create one.

6. Get your Username

   Your username is the same username you use to log in to the WMS system.

Keep Credentials Secure

Never expose your Master API Key in public code, repositories, or client-side JavaScript. Store credentials securely using environment variables or secret managers.

User Requirements

Your WMS user account must meet these requirements:

• UserLevel: Must be level 2 (warehouse user)
• Activated: Account must be activated (Activated = 'Y')
• Username: Must match exactly (case-sensitive)

Example Request

curl -X POST https://your-instance.shipedge.com/apirest/v4/wms/ping \
  -H "userName: manager" \
  -H "Key: abcde12345"

---

Response Format

Successful Responses

Successful API responses follow this structure:

{
  "data": {
    // Response data here
  }
}

Example - Ping endpoint:

{
  "data": {
    "status": "Successful",
    "result": "pong!"
  }
}

Error Responses

Error responses include details about what went wrong:

{
  "response": {
    "success": false,
    "message": "Error description here"
  }
}

HTTP Status Codes

• 200 - Success
• 400 - Invalid request (missing or incorrect parameters)
• 401 - Unauthorized (invalid credentials, user not activated, or insufficient permissions)
• 403 - Forbidden (no permissions)
• 404 - Not found (resource doesn’t exist)
• 500 - Server error

---

Main Endpoints

Status

Ping

Check system status and verify your authentication.

Endpoint: POST /ping

Headers: userName, Key

Response:

{
  "data": {
    "status": "Successful",
    "result": "pong!"
  }
}

---

Orders

Update Order Weight

Update the weight of an order after weighing the package. This endpoint is typically used when integrating with scale systems or after manual weighing.

Endpoint: POST /orders/UpdateWeight

Headers: userName, Key

Body:

{
  "data": [
    {
      "nbtybarcode": "abc123",
      "weight": 1.5
    }
  ]
}

Required Fields:

• nbtybarcode - Unique barcode or identifier for the order/package
• weight - Weight value as a float (e.g., 1.5 for 1.5 lbs)

Order Status Requirements:

• Order must be in Processing (status 4) or Shipped (status 9) status
• Order must exist and be associated with the barcode

Response:

{
  "response": {
    "success": true,
    "message": "Order is being updating"
  }
}

Common Errors:

• 400 - Missing required fields (nbtybarcode or weight)
• 400 - Invalid weight format (must be numeric)
• 400 - Order not found or not in correct status
• 400 - Order status doesn’t allow weight updates

Use Cases:

• Integration with digital scales
• Post-weighing updates after manual weighing
• Automated weight capture systems
• Weight verification workflows

---

Inventory

Get Product Bin Information

Retrieve detailed bin information for a specific product, including all locations and bins where the product is stored.

Endpoint: GET /inventory/products/{product_id}/bin

Headers: userName, Key

Path Parameters:

• product_id - Product ID (numeric)

Example:

GET /apirest/v4/wms/inventory/products/12345/bin

Response:

{
  "bin_list": [
    {
      "BinID": 1,
      "Location": "A-01",
      "Bin": "BIN-001",
      "Quantity": 50,
      "ProductID": 12345
    }
  ]
}

Use Cases:

• Warehouse management systems
• Inventory reporting
• Bin location lookups
• Stock level verification

---

Recounts

Perform Inventory Recount

Create and process inventory recounts to adjust bin quantities. This endpoint allows you to increase or decrease inventory levels in specific bins.

Endpoint: POST /recount

Headers: userName, Key

Body:

[
  {
    "account_id": 222,
    "comment": "Monthly inventory adjustment",
    "skus": [
      {
        "sku": "SKU_1",
        "bins": [
          {
            "location": "A-01",
            "bin": "BIN_1",
            "qty": 10
          },
          {
            "location": "A-01",
            "bin": "BIN_2",
            "qty": -5
          }
        ]
      },
      {
        "sku": "SKU_2",
        "bins": [
          {
            "location": "B-02",
            "bin": "BIN_3",
            "qty_in_bin": 100
          }
        ]
      }
    ]
  }
]

Required Fields:

• account_id - OMS account ID (numeric, must be activated)
• skus - Array of SKUs to recount
• skus[].sku - SKU identifier (must exist in system)
• skus[].bins - Array of bins for this SKU
• skus[].bins[].location - Location name (alphanumeric)
• skus[].bins[].bin - Bin name (alphanumeric)
• skus[].bins[].qty OR skus[].bins[].qty_in_bin - Quantity adjustment

Quantity Options:

• qty: Relative adjustment (adds or subtracts from current quantity)
  • Positive values increase quantity (e.g., 10 adds 10 units)
  • Negative values decrease quantity (e.g., -5 subtracts 5 units)
• qty_in_bin: Absolute value (sets the exact quantity in the bin)
  • Use when you know the exact current quantity
  • Replaces the existing quantity

Optional Fields:

• comment - Notes about the recount transaction (default: “Updated using the Recount API.”)

Response:

{
  "success": true,
  "message": "Success: {correction_account_id: 222, skus:SKU_1, correction_id: 12345}",
  "result": [
    {
      "account_id": 222,
      "sku": "SKU_1",
      "bin": "BIN_1",
      "location": "A-01",
      "correction_id": 12345,
      "error": false,
      "new_quantity": 60,
      "description": "Recount processed successfully"
    }
  ],
  "code": 200
}

Error Response:

{
  "success": false,
  "message": "Unsuccess: {no_create_recount_account_id: 222, skus:SKU_1}",
  "result": [
    {
      "account_id": 222,
      "sku": "SKU_1",
      "bin": "BIN_1",
      "location": "A-01",
      "error": true,
      "message": "Error description",
      "procces_correction": false
    }
  ],
  "code": 400
}

Common Errors:

• 400 - Missing required fields (account_id, skus, sku, bins, location, bin)
• 400 - Account not found or not activated
• 400 - SKU doesn’t exist
• 400 - Location or bin doesn’t exist
• 400 - Invalid quantity format
• 400 - Both qty and qty_in_bin provided (use only one)

Use Cases:

• Monthly inventory adjustments
• Cycle counting corrections
• Stock reconciliation after receiving
• Inventory corrections from audits
• Automated inventory adjustments

Important Notes:

• You can process multiple accounts in a single request (array format)
• Each SKU can have multiple bins in different locations
• The API processes recounts asynchronously - corrections are queued
• Check the correction_id in the response to track the recount
• Use qty for adjustments, qty_in_bin for absolute quantities

---

Shipments

Revert Shipment to Pending

Revert one or more shipments from Processing status back to Pending status. This is useful when corrections are needed before shipping.

Endpoint: POST /shipments/revert/pending

Headers: userName, Key

Body:

{
  "shipments_list": [262742, 263003]
}

Required Fields:

• shipments_list - Array of shipment IDs (order IDs) to revert

Requirements:

• Shipments must exist in the warehouse
• Shipments must be in Processing status (status 4)
• Shipments cannot be in other statuses (Shipped, Cancelled, etc.)

Response:

{
  "response": {
    "success": true,
    "message": "Your request had been accepted, will be processed soon."
  }
}

Error Response:

{
  "response": {
    "success": false,
    "message": "The shipments 262742, 263003 are not in processing status."
  }
}

Common Errors:

• 400 - Missing shipments_list field
• 400 - Empty shipments list
• 400 - Shipments don’t exist in warehouse
• 400 - Shipments are not in Processing status (must be status 4)

Use Cases:

• Correcting order errors before shipping
• Reverting shipments after quality control issues
• Undoing accidental processing
• Making changes to orders that are already processing

Important Notes:

• The operation is processed asynchronously
• Only shipments in Processing status can be reverted
• Multiple shipments can be reverted in a single request
• The response indicates the request was accepted, not that it’s complete

---

💡 Best Practices

Test with Ping First

Always test your authentication using the /ping endpoint before making more complex requests.

Validate Data Before Sending

Verify that orders exist and are in the correct status before updating weights or reverting shipments.

Use Appropriate Quantity Fields

Use qty for relative adjustments and qty_in_bin for absolute quantities. Don’t use both in the same request.

Handle Errors Gracefully

Always check HTTP status codes and handle errors appropriately. Review error messages for specific issues.

Store Credentials Securely

Never expose API keys in public code. Use environment variables, secret managers, or secure configuration files.

Verify Order Status

Before updating weights or reverting shipments, verify that orders are in the correct status for the operation.

Use Comments in Recounts

Always include meaningful comments in recount operations to track why adjustments were made.

Review Swagger Documentation

Use the interactive Swagger documentation at /apirest/v4/wms/docs to see the most recent endpoints and exact parameter requirements.

---

Swagger Documentation

ShipEdge Core includes interactive Swagger documentation for REST API v4 (WMS):

URL: https://your-instance.shipedge.com/apirest/v4/wms/docs

Features:

• Complete documentation of all endpoints
• Request and response examples
• Test endpoints directly from the browser
• See exact parameter requirements
• View response schemas

Access Requirements:

• Requires WMS session authentication
• You must be logged in to the WMS system to access Swagger

Interactive Testing

Use Swagger documentation to test endpoints directly without writing code. This helps verify your requests before implementing them in your application.

---

Troubleshooting

Error 401 - Unauthorized

Common causes:

• Incorrect or missing Master API Key
• Incorrect or missing Username
• User account not activated
• User doesn’t have warehouse permissions (UserLevel must be 2)
• User account doesn’t exist

Solution:

1. Verify your credentials in System Config > Preferences > Operations > Shipedge master API Key
2. Ensure your username matches exactly (case-sensitive)
3. Make sure your user account is activated (Activated = 'Y')
4. Verify your user has warehouse permissions (UserLevel = 2)
5. Check that you’re using the correct headers (userName and Key)

Error 400 - Invalid Request

Common causes:

• Missing required headers (userName or Key)
• Missing required parameters in the request body
• Incorrect data format or type
• Invalid values for fields
• Empty arrays or lists

Solution:

1. Verify that all required headers are present
2. Review Swagger documentation to see exact required parameters
3. Validate the JSON format of your request
4. Check that all required fields are included
5. Verify data types match requirements (strings vs integers, etc.)
6. Ensure arrays are not empty when required

Error 404 - Not Found

Common causes:

• Incorrect URL path
• Resource doesn’t exist (invalid Product ID, Order ID, etc.)
• Incorrect API version path

Solution:

1. Verify that the URL is correct (must include /apirest/v4/wms/)
2. Confirm that the resource ID exists in the system
3. Use Swagger documentation to see the exact URLs
4. Check that you’re using the correct identifier format

Update Weight Fails

Common causes:

• Missing nbtybarcode or weight fields
• Invalid weight format (must be numeric/float)
• Order not found for the barcode
• Order not in Processing or Shipped status

Solution:

1. Verify all required fields are included (nbtybarcode, weight)
2. Ensure weight is a valid number (e.g., 1.5, not "1.5" as string)
3. Check that the barcode exists and is associated with an order
4. Verify the order is in Processing (status 4) or Shipped (status 9) status
5. Review error message for specific field issues

Recount Fails

Common causes:

• Missing required fields (account_id, skus, location, bin)
• Account not found or not activated
• SKU doesn’t exist in the system
• Location or bin doesn’t exist
• Invalid quantity format
• Both qty and qty_in_bin provided (should use only one)

Solution:

1. Ensure all required fields are included
2. Verify the account ID exists and is activated
3. Check that SKUs exist in the system before recounting
4. Verify location and bin names match exactly (case-sensitive)
5. Use either qty (relative) or qty_in_bin (absolute), not both
6. Ensure quantities are valid integers
7. Review error message for specific field issues

Revert Shipment Fails

Common causes:

• Missing shipments_list field
• Empty shipments list
• Shipments don’t exist in warehouse
• Shipments are not in Processing status

Solution:

1. Verify shipments_list is included and is an array
2. Ensure the shipments list is not empty
3. Check that shipment IDs exist in the warehouse
4. Verify shipments are in Processing status (status 4)
5. Review error message for specific shipment issues

Responses Are Slow

Common causes:

• Large recount operations processing many SKUs
• Network latency
• Server processing time for complex operations

Solution:

1. Recount operations are processed asynchronously - check the response for correction_id
2. Break large operations into smaller batches if needed
3. Consider making parallel requests when possible (but respect rate limits)
4. Monitor API logs for performance issues

---

Related Links

• API Overview - General API information and comparison
• REST API v4 (OMS) - OMS endpoints documentation
• API v2 (Legacy) - Legacy API documentation
• Swagger Documentation - Access to interactive documentation
• Webhooks - Configure webhooks for automatic events

---

Next Step: REST API v4 (OMS) - Learn to use OMS endpoints for order and inventory management