REST API v4 (OMS)

The REST API v4 (OMS) allows you to programmatically manage orders, inventory, products, replenishments, and returns in your ShipEdge Order Management System account. This API uses standard RESTful endpoints with JSON responses.

Why Use REST API v4 (OMS)?

Automate Order Processing

Create, update, and cancel orders automatically from your eCommerce platform or ERP system.

Manage Inventory Programmatically

Add products, update stock levels, and manage your catalog without using the web interface.

Real-Time Synchronization

Keep your systems synchronized with ShipEdge in real-time to avoid data gaps or delays.

Bulk Operations

Process multiple orders, products, or serial numbers in a single API call for efficiency.

Base URL

All OMS API endpoints use this base URL:

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

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

Authentication

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

Required Headers

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

Getting Your Credentials

Log in to your ShipEdge OMS account

Access your ShipEdge account through the web interface.
Navigate to Preferences

Go to My Account > Preferences in the main menu.
Open API Integration section

Click on the API Integration tab in Preferences.
Find your credentials

You’ll see:
- AccountID: Your numeric account identifier
- Key: Your API key (click “Generate new Key” if needed)

Example Request

curl -X POST https://your-instance.shipedge.com/apirest/v4/oms/ping \
  -H "AccountID: 100" \
  -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 or account not activated)
403 - Forbidden (no permissions)
404 - Not found (resource doesn’t exist)
500 - Server error

Pagination

Endpoints that return lists support pagination via query parameters:

Parameters:

page: Page number (default: 1)
per_page: Items per page (default: varies by endpoint, typically 20)

Example:

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

Paginated Response:

{
  "data": [...],
  "metadata": {
    "page": 1,
    "per_page": 50,
    "total_records": 150,
    "total_pages": 3,
    "total_current_page": 50
  }
}

Main Endpoints

Status

Ping

Check system status and verify your authentication.

Endpoint: POST /ping

Headers: AccountID, Key

Response:

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

Orders

Create Order

Create one or more orders in your system.

Endpoint: POST /orders

Headers: AccountID, Key

Body:

{
  "data": [
    {
      "order_number": "ORD-001",
      "order_reference": "REF-123",
      "shipping_method": "Pick",
      "cart": {
        "store_name": "My Shop",
        "id": 0
      },
      "customer": {
        "email": "customer@example.com",
        "phone": "1234567890",
        "firstname": "John",
        "lastname": "Doe",
        "address1": "123 Main St",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90001",
        "country": "USA"
      },
      "items": [
        {
          "sku": "PROD-001",
          "quantity": 2,
          "sold_price": 29.99
        }
      ]
    }
  ]
}

Required Fields:

order_number - Unique order identifier
shipping_method - Shipping method code
customer.firstname - Customer first name
customer.address1 - Street address
customer.city - City
customer.state - State or province
customer.zip - Postal code
customer.country - Country
items - Array of order items
items[].sku - Product SKU
items[].quantity - Item quantity

List Orders

Get a paginated list of orders with optional filters.

Endpoint: GET /orders

Headers: AccountID, Key

Query Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20)
status_id - Filter by order status (optional)
from_date - Start date filter (optional)
to_date - End date filter (optional)
order_by - Sort field (default: OrderID)
order_direction - Sort direction: asc or desc (default: desc)
order_type_id - Filter by order type (optional)
warehouse_id - Filter by warehouse (optional)
filter_by - Filter type: cart_id, store_id, or store_name (optional)
filter_value - Filter value (optional)

Example:

GET /apirest/v4/oms/orders?page=1&per_page=50&status_id=3&from_date=2024-01-01

Get Order Details

Retrieve detailed information about a specific order.

Endpoint: GET /orders/{order}

Headers: AccountID, Key

Path Parameters:

order - Order ID, order number, or order reference

Query Parameters:

identify_by - How to identify the order: order_id, order_number, order_reference, or order_api (default: order_id)

Example:

GET /apirest/v4/oms/orders/12345?identify_by=order_id

Update Order

Update an existing order.

Endpoint: PUT /orders

Headers: AccountID, Key

Body: Same structure as Create Order, but include order identifier

Cancel Order

Cancel a single order.

Endpoint: POST /orders/cancel

Headers: AccountID, Key

Body:

{
  "order_id": 12345
}

Cancel Orders (Bulk)

Cancel multiple orders at once.

Endpoint: POST /orders/cancel-bulk

Headers: AccountID, Key

Body:

{
  "order_ids": [12345, 12346, 12347]
}

Update Order Sub-Status

Update the sub-status of an order.

Endpoint: POST /orders/sub_status

Headers: AccountID, Key

Body:

{
  "order_id": 12345,
  "sub_status": "Custom Status"
}

Inventory - Products

List Products

Get a paginated list of products in your inventory.

Endpoint: GET /inventory/products

Headers: AccountID, Key

Query Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20)
order_by - Sort field (default: ProductID)
order_direction - Sort direction: asc or desc (default: desc)

Example:

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

Create Product

Add one or more products to your inventory.

Endpoint: POST /inventory/products

Headers: AccountID, Key

Body:

{
  "data": [
    {
      "sku": "PROD-001",
      "description": "Product description",
      "width": 10,
      "length": 10,
      "height": 5,
      "weight": 1,
      "cost": 10.00,
      "retail": 29.99,
      "upc": "123456789012",
      "supplier": "Supplier Name",
      "distribution_center": "DC-CODE",
      "pick_style": "STANDARD"
    }
  ]
}

Required Fields:

sku - Product SKU (cannot be changed after creation)
description - Product description
width - Product width
length - Product length
height - Product height
weight - Product weight
cost - Product cost
retail - Retail price

Optional Fields:

upc - UPC or barcode
harmonization_code - Harmonization Code (HTS)
supplier - Supplier name (must be registered)
distribution_center - Distribution center code (must be registered)
package_type - Package type (must be registered)
pick_style - Pick style: STANDARD, SAVE_SPACE, FIFO, LIFO, FEFO, FLFO, LLFO, BIN_ASC, BIN_DESC
one_time_product - Yes, Y, YES, No, N, NO (default: No)
case_qty - Units per case/carton
category - Product family
model - Product model or family
manufacturer - Manufacturer name
client_option1, client_option2, client_option3 - Custom fields
image_url - URL for product image import

Update Product

Update product information.

Endpoint: PATCH /inventory/products

Headers: AccountID, Key

Body: Same structure as Create Product, but SKU cannot be changed

Get Product Details

Retrieve detailed information about a specific product.

Endpoint: GET /inventory/products/{prod_identifier}

Headers: AccountID, Key

Path Parameters:

prod_identifier - Product ID or SKU

Example:

GET /apirest/v4/oms/inventory/products/PROD-001

Get Product Units of Measure

Get units of measure (UOM) for a product.

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

Headers: AccountID, Key

Path Parameters:

product_id - Product ID

Get Stock Levels

Get current stock levels for products.

Endpoint: GET /inventory/stock

Headers: AccountID, Key

Query Parameters:

sku - Filter by SKU (optional)
distribution_center - Filter by distribution center (optional)

Example:

GET /apirest/v4/oms/inventory/stock?sku=PROD-001

Inventory - Aliases (Translators)

Aliases allow you to map external SKUs to your internal SKUs for integrations.

List Aliases

Get a paginated list of aliases/translators.

Endpoint: GET /inventory/aliases

Headers: AccountID, Key

Query Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20)
channel_id - Filter by channel ID (optional)
distribution_center - Filter by distribution center (optional)

Create Alias

Create a new alias/translator mapping.

Endpoint: POST /inventory/aliases

Headers: AccountID, Key

Body:

{
  "data": [
    {
      "sku": "INTERNAL-SKU",
      "alias": "EXTERNAL-SKU",
      "channel_id": 1,
      "distribution_center": "DC-CODE"
    }
  ]
}

Update Alias

Update an existing alias/translator.

Endpoint: PATCH /inventory/aliases

Headers: AccountID, Key

Body: Same structure as Create Alias

Get Alias Details

Get details about a specific alias.

Endpoint: GET /inventory/aliases/{alias}

Headers: AccountID, Key

Path Parameters:

alias - Alias identifier

Inventory - Synsets (Product Families)

Synsets allow you to group multiple SKUs together as kits, bundles, or product families.

List Synsets

Get a paginated list of synsets.

Endpoint: GET /inventory/synsets

Headers: AccountID, Key

Query Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20)

Create Synset

Create a new synset (product family).

Endpoint: POST /inventory/synsets

Headers: AccountID, Key

Body:

{
  "data": [
    {
      "synset": "BUNDLE-001",
      "items": [
        {
          "sku": "SKU-1",
          "quantity": 1
        },
        {
          "sku": "SKU-2",
          "quantity": 2
        }
      ]
    }
  ]
}

Update Synset

Update an existing synset.

Endpoint: PATCH /inventory/synsets

Headers: AccountID, Key

Body: Same structure as Create Synset

Get Synset Details

Get details about a specific synset.

Endpoint: GET /inventory/synsets/{synset}

Headers: AccountID, Key

Path Parameters:

synset - Synset name

Replenishments

Create Replenishment

Create a new replenishment request.

Endpoint: POST /inventory/replenishments

Headers: AccountID, Key

Body:

{
  "data": [
    {
      "items": [
        {
          "sku": "PROD-001",
          "quantity": 100
        }
      ],
      "distribution_center": "DC-CODE",
      "eta": "2024-12-31"
    }
  ]
}

List Replenishments

Get a paginated list of replenishments.

Endpoint: GET /inventory/replenishments

Headers: AccountID, Key

Query Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20)

Update Replenishment

Update an existing replenishment.

Endpoint: PATCH /inventory/replenishments

Headers: AccountID, Key

Body: Same structure as Create Replenishment

Get Replenishment Details

Get details about a specific replenishment.

Endpoint: GET /inventory/replenishments/{replenishment}

Headers: AccountID, Key

Path Parameters:

replenishment - Replenishment ID

Returns

Create Return

Create a new return order.

Endpoint: POST /inventory/returns

Headers: AccountID, Key

Body:

{
  "data": [
    {
      "order_id": 12345,
      "items": [
        {
          "sku": "PROD-001",
          "quantity": 1,
          "reason": "Defective"
        }
      ]
    }
  ]
}

List Returns

Get a paginated list of returns.

Endpoint: GET /inventory/returns

Headers: AccountID, Key

Query Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20)

Get Return Details

Get details about a specific return.

Endpoint: GET /inventory/returns/{return}

Headers: AccountID, Key

Path Parameters:

return - Return ID

Serial Numbers

Create Serials (Bulk)

Create serial numbers in bulk for products.

Endpoint: POST /serials/bulk

Headers: AccountID, Key

Body:

{
  "data": [
    {
      "sku": "PROD-001",
      "serials": ["SN001", "SN002", "SN003"]
    }
  ]
}

Add Attributes to Serial Range

Add attributes to a range of serial numbers.

Endpoint: POST /serials/batch/attributes

Headers: AccountID, Key

Body:

{
  "data": [
    {
      "sku": "PROD-001",
      "serial_start": "SN001",
      "serial_end": "SN100",
      "attributes": [
        {
          "attribute": "lot",
          "value": "LOT-001"
        }
      ]
    }
  ]
}

Attributes

Attributes allow you to add custom metadata to orders, products, or other entities.

Get Attributes

Get attributes for a specific owner (order, product, etc.).

Endpoint: GET /attributes/{owner_type}/{owner_id}

Headers: AccountID, Key

Path Parameters:

owner_type - Type of owner (e.g., order, product)
owner_id - ID of the owner

Query Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20)

Create Attribute

Create a new attribute for an owner.

Endpoint: POST /attributes/{owner_type}/{owner_id}

Headers: AccountID, Key

Path Parameters:

owner_type - Type of owner
owner_id - ID of the owner

Body:

{
  "data": [
    {
      "attribute": "custom_field",
      "value": "custom_value"
    }
  ]
}

Update Attribute

Update an existing attribute.

Endpoint: PATCH /attributes/{owner_type}/{owner_id}

Headers: AccountID, Key

Path Parameters:

owner_type - Type of owner
owner_id - ID of the owner

Body: Same structure as Create Attribute

Delete Attribute

Delete an attribute.

Endpoint: DELETE /attributes/{owner_type}/{owner_id}

Headers: AccountID, Key

Path Parameters:

owner_type - Type of owner
owner_id - ID of the owner

Query Parameters:

attribute - Attribute name to delete

Distribution Centers

List Distribution Centers

Get a list of all distribution centers.

Endpoint: GET /distribution_centers

Headers: AccountID, Key

Get Distribution Center Details

Get details about a specific distribution center.

Endpoint: GET /distribution_centers/{distribution_center_id}

Headers: AccountID, Key

Path Parameters:

distribution_center_id - Distribution center ID

Manufacture

List Manufacture Orders

Get a paginated list of manufacture orders.

Endpoint: GET /manufacture

Headers: AccountID, Key

Query Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20)

Get Manufacture Order Details

Get details about a specific manufacture order.

Endpoint: GET /manufacture/{order}

Headers: AccountID, Key

Path Parameters:

order - Manufacture order ID

💡 Best Practices

Test with Ping First

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

Use Pagination

For large listings, always use pagination instead of trying to get all data at once. This improves performance and reduces server load.

Handle Errors Gracefully

Always check HTTP status codes and handle errors appropriately in your code. Implement retry logic for transient errors.

Validate Data Before Sending

Validate required fields and data formats before sending requests to avoid 400 errors.

Store Credentials Securely

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

Use Bulk Operations

When processing multiple items, use bulk endpoints (like bulk cancel or bulk serial creation) instead of multiple individual requests.

Respect Rate Limits

Implement rate limiting in your code to avoid overloading the API. Space out requests appropriately.

Review Swagger Documentation

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

Swagger Documentation

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

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

Features:

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

Troubleshooting

Error 401 - Unauthorized

Common causes:

Incorrect or expired API Key
Incorrect AccountID
Account not activated

Solution:

Verify your credentials in My Account > Preferences > API Integration
Make sure your account is activated
Regenerate your API Key if necessary
Check that you’re using the correct headers (AccountID and Key)

Error 400 - Invalid Request

Common causes:

Missing required headers (AccountID or Key)
Missing required parameters in the request body
Incorrect data format or type
Invalid values for fields

Solution:

Verify that all required headers are present
Review Swagger documentation to see exact required parameters
Validate the JSON format of your request
Check that all required fields are included
Verify data types match requirements (strings vs integers, etc.)

Error 404 - Not Found

Common causes:

Incorrect URL path
Resource doesn’t exist (invalid ID or SKU)
Incorrect API version path

Solution:

Verify that the URL is correct (must include /apirest/v4/oms/)
Confirm that the resource ID exists in the system
Use Swagger documentation to see the exact URLs
Check that you’re using the correct identifier (ID vs SKU vs order number)

Responses Are Slow

Common causes:

Requests without pagination for large listings
Multiple sequential requests instead of bulk operations
Large response payloads

Solution:

Use pagination for large listings (page and per_page parameters)
Use bulk endpoints when processing multiple items
Use filters to reduce the amount of data returned
Consider making parallel requests when possible (but respect rate limits)

Order Creation Fails

Common causes:

Missing required fields
Invalid SKU (product doesn’t exist)
Invalid shipping method code
Invalid store name or channel ID

Solution:

Verify all required fields are included (order_number, shipping_method, customer fields, items)
Ensure products exist in inventory before creating orders
Check shipping method codes in your account
Verify store name matches exactly or use channel ID instead
Review error message for specific field issues

Product Creation Fails

Common causes:

SKU already exists (SKU cannot be changed after creation)
Missing required fields
Invalid supplier or distribution center names
Invalid pick_style value

Solution:

Check if SKU already exists (use GET endpoint first)
Ensure all required fields are included (sku, description, dimensions, weight, cost, retail)
Verify supplier and distribution center names match exactly (case-sensitive)
Use valid pick_style values: STANDARD, SAVE_SPACE, FIFO, LIFO, FEFO, FLFO, LLFO, BIN_ASC, BIN_DESC

API Overview - General API information and comparison
REST API v4 (WMS) - WMS 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 (WMS) - Learn to use WMS endpoints for warehouse operations