API Overview

The ShipEdge Core API allows you to integrate your system with ShipEdge to manage orders, inventory, and warehouse operations programmatically. You can create, read, update, and delete data using standard REST endpoints.

ShipEdge Core offers two main API versions: API v4 (modern and recommended) and API v2 (legacy for compatibility). Each version is designed for different use cases and access levels.

Quick Start

To get started, you need your AccountID and API Key which you can find in Preferences > API Integration in your ShipEdge account.

Why Use the API?

Complete Automation

Integrate ShipEdge with your eCommerce system, ERP, or any custom application to automate processes.

Programmatic Management

Create, update, and manage orders, products, and inventory through code instead of using the web interface.

Real-Time Synchronization

Keep your systems synchronized with ShipEdge in real-time to avoid information gaps.

Scalability

Process large volumes of data efficiently using optimized endpoints with pagination.

---

Available API Versions

ShipEdge Core offers two main API versions:

API v4 (REST API - Recommended)

Base URL: /apirest/v4/

API v4 is the modern and recommended version for new integrations. It’s built with Slim Framework and offers standard RESTful endpoints.

Main features:

• Standard RESTful endpoints (GET, POST, PUT, PATCH, DELETE)
• Authentication via API Key and AccountID in headers
• Structured JSON responses
• Built-in pagination for large listings
• Swagger documentation available
• Clear separation between OMS and WMS

Subdivisions:

• OMS API (/apirest/v4/oms/): For order and inventory management from OMS
• WMS API (/apirest/v4/wms/): For warehouse operations from WMS

API v2 (Legacy)

Base URL: /apiv2/

API v2 is the legacy version maintained for compatibility with existing systems and mobile applications.

Main features:

• Specific endpoints for mobile applications (eXos)
• Endpoints for Pro WMS operations
• Authentication via API Key and AccountID
• Support for JWT tokens in some endpoints

Use cases:

• Existing mobile applications (eXos)
• Legacy integrations that still depend on v2
• Specific Pro WMS operations

---

Authentication

All APIs require authentication via HTTP headers. The exact method varies by API version:

API v4 (OMS and WMS)

Required headers:

AccountID: [Your numeric AccountID]
Key: [Your API Key]

Where to find your credentials:

• OMS: Go to My Account > Preferences > API Integration
• WMS: Go to System Config > Preferences > Operations > Shipedge master API Key

Request example:

curl -X POST https://your-instance.shipedge.com/apirest/v4/oms/ping \
  -H "AccountID: 100" \
  -H "Key: abcde12345"

API v2

Required headers:

AccountID: [Your numeric AccountID]
Authorization: [Your API Key]

Or alternatively:

AccountID: [Your numeric AccountID]
Key: [Your API Key]

---

Main Endpoints

API v4 OMS - Main Endpoints

Orders:

• POST /orders - Create order
• GET /orders - List orders (with pagination)
• GET /orders/{order} - Get order details
• PUT /orders - Update order
• POST /orders/cancel - Cancel order
• POST /orders/cancel-bulk - Cancel multiple orders
• POST /orders/sub_status - Update sub-status

Inventory:

• GET /inventory/products - List products (with pagination)
• POST /inventory/products - Create product
• PATCH /inventory/products - Update product
• GET /inventory/products/{id} - Get product
• GET /inventory/stock - Get stock levels
• GET /inventory/products/{id}/uom - Get units of measure

Replenishments:

• POST /inventory/replenishments - Create replenishment
• GET /inventory/replenishments - List replenishments
• PATCH /inventory/replenishments - Update replenishment
• GET /inventory/replenishments/{id} - Get replenishment

Returns:

• POST /inventory/returns - Create return
• GET /inventory/returns - List returns
• GET /inventory/returns/{id} - Get return

Others:

• POST /ping - Verify system status
• GET /distribution_centers - List distribution centers
• POST /serials/bulk - Create serial numbers in bulk
• GET /attributes/{type}/{id} - Get attributes
• POST /attributes/{type}/{id} - Create attribute

API v4 WMS - Main Endpoints

Warehouse Operations:

• POST /ping - Verify system status
• POST /orders/UpdateWeight - Update order weight
• POST /recount - Perform inventory recount
• POST /shipments/revert/pending - Revert shipment to pending
• GET /inventory/products/{product_id}/bin - Get product bins

API v2 - Main Endpoints

Mobile Application (eXos):

• POST /exos-login-1 - User login
• POST /exos-verify-code-1 - Verify 2FA code
• POST /exos-v1/pp-getOrders-1 - Get orders for picking
• POST /exos-v1/pp-updateLogPick-1 - Update picking log
• POST /exos-v1/pp-move-1 - Move inventory
• POST /exos-v1/qc-shippings-1 - Get shipments for QC

Pro WMS:

• POST /pro-v1/inventory-list-1 - Get inventory list
• POST /pro-v1/put-away-load - Load for put-away
• POST /pro-v1/put-away-move - Move in put-away

---

Response Structure

Successful Responses

Successful responses generally follow this format:

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

Ping response example:

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

Error Responses

Error responses include information about what went wrong:

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

Common HTTP status codes:

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

---

Pagination

Endpoints that return lists (like /orders or /products) support pagination via query parameters:

Parameters:

• page: Page number (default: 1)
• per_page: Items per page (default: varies by endpoint)

Example:

GET /apirest/v4/oms/orders?page=1&per_page=50

Paginated response:

{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3
  }
}

---

Swagger Documentation

ShipEdge Core includes interactive Swagger documentation to explore all available endpoints:

API v4 OMS Swagger:

• URL: https://your-instance.shipedge.com/apirest/v4/oms/docs
• Complete documentation of all OMS endpoints
• Request and response examples
• Test endpoints directly from the browser

API v4 WMS Swagger:

• URL: https://your-instance.shipedge.com/apirest/v4/wms/docs
• Complete documentation of all WMS endpoints
• Requires WMS session authentication

---

💡 Best Practices

Use API v4

For new integrations, always use API v4. It’s more modern, better documented, and has better support.

Handle Errors

Always check HTTP status codes and handle errors appropriately in your code.

Respect Limits

Implement rate limiting in your code to avoid overloading the API. Some endpoints have usage limits.

Use Pagination

For large listings, always use pagination instead of trying to get all data at once.

Store Credentials Securely

Never expose your API keys in public code or repositories. Use environment variables or secret managers.

Test with Ping

Use the /ping endpoint to verify your authentication works before making more complex requests.

Review Logs

If you have issues, review API logs on the server to understand what’s happening.

Updated Documentation

Consult Swagger documentation to see the most recent endpoints and their exact parameters.

---

Troubleshooting

Error 401 - Unauthorized

Common causes:

• Incorrect or expired API Key
• Incorrect AccountID
• Account not activated

Solution:

1. Verify your credentials in Preferences > API Integration
2. Make sure your account is activated (Activated = Y)
3. Regenerate your API Key if necessary

Error 400 - Invalid Request

Common causes:

• Missing headers (AccountID or Key)
• Missing required parameters in the body
• Incorrect data format

Solution:

1. Verify that all required headers are present
2. Review Swagger documentation to see the exact required parameters
3. Validate the JSON format of your request

Error 404 - Not Found

Common causes:

• Incorrect URL
• Resource doesn’t exist (invalid ID)
• Incorrect API version

Solution:

1. Verify that the URL is correct (including /apirest/v4/oms/ or /apirest/v4/wms/)
2. Confirm that the resource ID exists in the system
3. Use Swagger documentation to see the exact URLs

Responses Are Slow

Common causes:

• Requests without pagination for large listings
• Multiple sequential requests instead of a single one

Solution:

1. Use pagination for large listings
2. Consider making parallel requests when possible
3. Use filters to reduce the amount of data returned

---

Related Links

• REST API v4 (OMS) - Detailed OMS endpoints documentation
• REST API v4 (WMS) - Detailed WMS endpoints documentation
• API v2 (Legacy) - API v2 documentation for compatibility
• Authentication - Detailed authentication guide
• Webhooks - Configure webhooks for automatic events
• Swagger Documentation - Access to interactive documentation

---

Next Step: REST API v4 (OMS) - Learn to use OMS endpoints to manage orders and inventory