Menu

Interaction Guide for WMS Integrations

Avatar
Daniel Norman
  • Updated
Follow

Interaction Guide for WMS integrations

Integrating WMS providers with RetailOps is a snap with our simple API. RetailOps uses a JSON API that's easy to use in any language.

Summary of Integrations

  1. ASN Retrieval
  2. ASN Acknowledgement
  3. Inventory Receipt Recording
  4. Inventory Adjustment
  5. Shipment Retrieval
  6. Shipment Acknowledgement
  7. Shipment Completion and Tracking
  8. RMA Retrieval 
  9. Return Submit

Key Concepts

See our Developer Portal for more information on using the RetailOps API.

1. ASN Retrieval

For WMS integrations, your WMS must receive an ASN notifying them of deliveries that are scheduled to be sent to their facility. ASNs may provide info on POs, BOLs, quantities, and configurations of items in shipment. This allows the vendor to plan space and allocate resources accordingly. Vendors must retrieve ASNs in “Pending” status.

Note that ASN generation must be turned on by RetailOps for each vendor.

To retrieve ASNs, use API call Fulfillment.ASN.fetch - Version 1. See a sample below.

curl -X POST 'https://api.gudtech.com/fulfillment/asn/fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "facility_id": 20,
        "status": "pending",
        "start":0,
        "limit": 10
    }'

2. ASN Acknowledgement

Once your WMS acknowledges that they have received an ASN, the ASN will no longer be retrieved by the ASN Retrieval call. Your WMS may acknowledge up to 100 ASNs per call.

To acknowledge receipt of ASNs, use API call Fulfillment.ASN.acknowledge - Version 1. See a sample below.

curl -X POST 'https://api.gudtech.com/fulfillment/asn/acknowledge~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "id": [1,2,3]
    }'

3. Inventory Receipt Recording

Each lot represents the receipt of some quantity of a SKU at a specific time. Your WMS may create up to 100 lots per call.

To create lots, use API call Inventory.Lot.create - Version 1. Note that: 1. the parameter asn_item_id is highly preferred; 2. either SKU or VPC is required as a parameter, not both.

See a sample below.

curl -X POST 'https://api.gudtech.com/inventory/lot/create~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "sku": "S123",
        "asn_item_id":12345,
        "quantity": 1,
        "container": "Some Container Name",
        "container_facility_id": 1,
        "no_label": true
    }' 

4. Inventory Adjustment

Step 1 – Fetch Reason Code

Inventory may be adjusted for a number of different reasons. In order to assign a specific inventory adjustment to a reason code, you must first fetch the reason codes configured for a customer instance. See a sample of how to fetch reasons below.

curl -X POST 'https://api.retailops.com/Config/Inventory/AdjustmentReason/fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{}'

Step 2 – Adjust Inventory

Inventory adjustments may be made from time to time. To adjust inventory for a SKU you may specify the quantity you'd like to adjust, whether it is to be incremented or decremented or moved.

Incrementing quantities

Increment with lot ID:

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "add",
        "quantity": 10,
        "lot_id": 123,
        "container_id": 789,
        "reason_id": 1
    }'

Increment with lot ID and container name:

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "add",
        "quantity": 10,
        "lot_id": 123,
        "container": "A-B-1",
        "reason_id": 1
    }'

Increment using container facility ID, which will allow the system to create the container if doesn't exist:

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "add",
        "quantity": 10,
        "lot_id": 123,
        "container": "A-B-1",
        "container_facility_id": 1,
        "reason_id": 1
    }'

Increment using "sku mode" with a SKU number, which will automatically locate an appropriate lot to increment:

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "add",
        "quantity": 10,
        "sku_mode": true,
        "sku_num": "ABC123",
        "container": "A-B-1",
        "container_facility_id": 1,
        "reason_id": 1
   }'

Decrementing quantities

Decrement using lot ID and container name:

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "subtract",
        "quantity": 10,
        "lot_id": 123,
        "container": "A-B-1",
        "reason_id": 2
    }'

Decrement using SKU number and container name:

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "subtract",
        "quantity": 10,
        "sku_num": "ABC123",
        "container": "A-B-1",
        "reason_id": 2
    }'

Decrement using all-or-none flag, which will return an error if the requested quantity amount is not available. Without this flag, a quantity less than requested will be decremented without returning an if the full amount is not available.

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "subtract",
        "quantity": 10,
        "lot_id": 123,
        "container": "A-B-1",
        "reason_id": 2,
        "allornone": true
    }'

Moving quantities

Move quantity from one container to another using lot ID and container names:

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "move",
        "quantity": 10,
        "lot_id": 123,
        "container": "A-B-1",
        "to_container": "C-D-2",
        "reason_id": 3,
   }'

Move quantity using SKU number:

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "move",
        "quantity": 10,
        "sku_num": "ABC123",
        "container": "A-B-1",
        "to_container": "C-D-2",
        "reason_id": 3,
    }'

Move quantity using all-or-none flag, which will return an error if the requested quantity amount is not available. Without this flag, a quantity less than requested will be decremented without returning an if the full amount is not available.

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "move",
        "quantity": 10,
        "sku_num": "ABC123",
        "container": "A-B-1",
        "to_container": "C-D-2",
        "reason_id": 3,
        "allornone": true
    }'

Move quantity using to container facility ID, which will allow the system to create the container if doesn't exist:

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "move",
        "quantity": 10,
        "sku_num": "ABC123",
        "container": "A-B-1",
        "to_container": "C-D-2",
        "to_container_facility_id": 1,
        "reason_id": 3,
    }'

Move quantity for Order Shipment picks. In order for the RetailOps reporting system to reflect inventory adjustments that result from successful shipments, inventory pick actions must be recorded as inventory moves with the associated shipment or shipment item notated.

curl -X POST 'https://api.retailops.com/Inventory/Quantity/Adjust~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "action": "move",
        "quantity": 10,
        "sku_num": "ABC123",
        "container": "A-B-1",
        "to_container": "SHIP-LOCATION",
        "to_container_facility_id": 1,
        "ref_shipment_item_id": 74294,
        "reason_id": 6
    }'

5. Shipment Retrieval

In RetailOps, customer orders are subdivided into shipments, each of which must be fulfilled by one of your distribution centers, by one of your Dropship vendors, or by one of your 3PL vendors. For WMS system providers, the WMS must retrieve shipments in a status of "Ready" and for the facility in which the WMS is operating to ship them to the customer.

To retrieve "Ready" shipments, use API call Fulfillment.Shipment.fetch - Version 1. See a sample below specifying the appropriate facility_id where the WMS is operating.

curl -X POST 'https://api.gudtech.com/fulfillment/shipment/fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{ 
        "facility_id":7, 
        "status":"ready",
        "with_ship_address":1,
        "with_order":1,
        "with_ship_service":1,
        "with_shipment_items":1,
        "limit":100,"start":0
    }'

6. Shipment Acknowledgement

In order to notify RetailOps that a shipment is being processed, you or your vendor must acknowledge transmission of the shipment immediately upon pickup. You must not ship a RetailOps shipment prior to successful acknowledgement. This is necessary to ensure the shipment is not rerouted or edited while you are processing it. Shipment acknowledgement also ensures that a given shipment will be excluded from subsequent retrievals of "Ready" shipments.

To acknowledge receipt of a RetailOps shipment, use API call Fulfillment.Shipment.MarkTransmitted - Version 1. See a sample below.

curl -X POST 'https://api.gudtech.com/fulfillment/shipment/marktransmitted~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "records": [{
            "id": 178382,
            "estimated_ship_date":"2014-03-18T16:00:00-07:00",
            "latest_ship_date":"2014-03-20T16:00:00-07:00"
        }]
    }'

7. Shipment Completion and Tracking

When your vendor has concluded the fulfillment of a shipment--whether successfully in whole, successfully in part, or unsuccessfully--the disposition of this shipment must be conveyed to RetailOps. The following two API interactions will facilitate this.

 

Step 1 - Retrieve Ship Carrier Class

There are a great many shipping carriers out there: Fedex, UPS, USPS, ONTRAC, and DHL are just the tip of the iceberg. In order to accurately express all these different carriers and their service classes ("Standard Overnight", "Priority Overnight", etc) to your various upstream channels, we must use a globally enumerated list of these classes, rather than just a text description. In order to complete the next step, you or your vendor will need to retrieve a list of all Ship Carrier Classes recognized by RetailOps, and select the correct one for your circumstance.

To retrieve a list of recognized Ship Carrier Classes, use API call Constant.Ship.CarrierClass.Fetch - Version 1. See a sample below.

curl -X POST 'https://api.gudtech.com/constant/ship/carrierclass/fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{ "all": 1 }'

 

Step 2 - Shipment Completion

Once a Ship Carrier Class has been selected, and the shipment has been fulfilled to the greatest extent possible, you or your vendor must complete the shipment.

All packages shipped--and all items and item quantities in each package shipped--should be reflected in association with each package. A unit_count per package is required for verification purposes, and must add up to the total number of items in that package. If any items are unavailable, you must provide the cancel_remainder flag to indicate that any non-referenced items were not shipped.

To complete the shipment, use API call Fulfillment.Shipment.Complete - Version 1. See a sample below. Optionally, you may include the `packages.item.decrement_inventory` parameter to have inventory deducted from the shipping container corresponding to the ship action. One or more decrement can be specified for each package item.

If only one decrement is specified for an item, the quantity can be omitted and will default to the item quantity, as below:

curl -X POST 'https://api.gudtech.com/fulfillment/shipment/complete~1.json' \
    -H 'Content-Type: application/json' \ 
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "id":165,
        "cancel_remainder": false,
        "packages": [{
            "ship_class_id": 5,
            "tracking_number": "1234567890123456",
            "unit_count": 2,
            "weight": 1.2,
            "cost": 12.34,
            "items": [{
                "sku": "877798039128",
                "quantity": 1,
                "decrement_inventory": {
                    "container": "ABC"
                }
            }, {
                "sku": "728217404960",
                "quantity": 1,
                "decrement_inventory": {
                    "container": "ABC"
                }
            }]
        }]
    }'

Multiple decrements can be specified per package item, as below:

curl -X POST 'https://api.gudtech.com/fulfillment/shipment/complete~1.json' \
    -H 'Content-Type: application/json' \ 
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "id":165,
        "cancel_remainder": false,
        "packages": [{
            "ship_class_id": 5,
            "tracking_number": "1234567890123456",
            "unit_count": 3,
            "weight": 1.2,
            "cost": 12.34,
            "items": [{
                "sku": "877798039128", 
                "quantity": 2, 
                "decrement_inventory": [{
                    "container": "ABC",
                    "quantity": 1
                }, {
                    "container": "DEF",
                    "quantity": 1
                }]
            }, {
                "sku": "728217404960",
                "quantity": 1,
                "decrement_inventory": {
                    "container": "ABC"
                }
            }]
        }]
    }'

8. RMA Retrieval

RMA records can be retrieved using the "customer.rma.fetch~1" API action. Available parameters:

rma_id
status
created_since
page
limit

It is required to specify the "rma_id" or "status" parameter; other parameters are optional. See the examples below for how to retrieve RMA records using these parameters.

curl -X POST 'https://api.retailops.com/customer.rma.fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{ 
        "rma_id": 123
    }'

Retrieve multiple RMAs by ID:

curl -X POST 'https://api.retailops.com/customer.rma.fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{ 
        "rma_id": [123, 124, 125]
    }'

Retrieve RMAs by status (available statuses are "incomplete", "complete", "closed"):

curl -X POST 'https://api.retailops.com/customer.rma.fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "status": "complete"
    }'

Retrieve RMAs by multiple statuses:

curl -X POST 'https://api.retailops.com/customer.rma.fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "status": ["complete", "closed"]
    }'

Retrieve RMAs created since a given date (accepted formats include unixtime and ISO8601):

curl -X POST 'https://api.retailops.com/customer.rma.fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "status": "complete",
        "created_since": "2020-07-01T00:00:00"
    }'
curl -X POST 'https://api.retailops.com/customer.rma.fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "status": "complete",
        "created_since": 1593561600
    }'

The results for the "customer.rma.fetch" action are paginated. Pages of 100 records are returned by default. The size of the page can be changed by using the "limit" parameter (with a maximum of 1,000 records). Subsequent pages are retrieved by specifying the "start" parameter. The example below shows how to retrieve the third in a series of pages of 200 records:

curl -X POST 'https://api.retailops.com/customer.rma.fetch~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "status": "complete",
        "start": 400,
        "limit": 200
    }'

9. Return Submit

To record the processing of a return, make an API call similar to the following. RetailOps will automatically look up the provided RMA ID, and apply appropriate values from each RMA item to each Return Item, including reason_id, do_restock, do_refund, do_shipping, give_shipping_amt, and restocking_fee The example below shows how to submit a return against RMA ID 1234. 
curl -X POST 'https://api.retailops.com/customer/order/return/submit~1.json' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
        "facility_id": X,
        "rma_id": 1234,
        "action_item_text": "Optional text which if specified will create an action item alert for customer service",
        "items": [{"sku":"S123", "quantity":1 }]
    }'

 

Related articles

Comments

0 comments

Please sign in to leave a comment.