Interaction Guide for Third-Party Logistics (3PL) Integrations

Integrating 3PL providers with RetailOps is a snap with our simple API. RO uses a JSON API that's easy to use in any language. Complete the following API interactions to start shipping.

Key Concepts

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

1. Inventory Advice

For external SKUs and their inventory, RO is not the system of record. The vendor manages this inventory so the vendor's system is the system of record. Because of this, RO must receive regular updates from the vendor regarding the inventory levels. These updates are called inventory advice. In RO, inventory advice is tracked against a vendor and a vendor product code (VPC).

To set inventory advice for a given VPC, use API call Product.ExternalSku.Update - Version 2. See a sample below.

curl -X POST '' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{ "records": [{ "vendor_id":"27","vpc":"ABC123","quantity":12 }] }'

2. Shipment Retrieval

In RO, 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 3PL vendors, the vendor must retrieve shipments in a status of "Ready" and ship them to the customer.

To retrieve "Ready" shipments, use API call Fulfillment.Shipment.fetch - Version 1. See a sample below.

curl -X POST '' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{ 
          "vendor_id":20, "type":"dropship", "status":"ready",

3. Shipment Acknowledgement

In order to notify RO 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 an RO shipment, use API call Fulfillment.Shipment.MarkTransmitted - Version 1. See a sample below.

curl -X POST '' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{ "records":[
            "id": 178382,

4. 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 RO. 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 RO, 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 '' \
  -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.

curl -X POST '' \
  -H 'Content-Type: application/json' \ 
  -H 'apikey: YOUR_APIKEY_GOES_HERE' \
  -d '{
       "cancel_remainder": 0,
           "unit_count": 6,
           "weight": 1.2,
           "cost": 12.34,
               {"vpc":"877798039128", "quantity":1},
               {"vpc":"728217404960", "quantity":1},
               {"vpc":"732995547078", "quantity":1},
               {"vpc":"877798003236", "quantity":1},
               {"vpc":"877798003250", "quantity":1},
               {"vpc":"X62065440011", "quantity":1}

5. ASN Retrieval

For 3PL integrations, your 3PL vendor 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 GudTech for each vendor.

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

curl -X POST '' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{

6. ASN Acknowledgement

Once your 3PL vendor acknowledges that they have received an ASN, the ASN will no longer be retrieved by the ASN Retrieval call. Your 3PL vendor 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 '' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
          "id": [1,2,3],

7. External Lot Creation

External lots are lots stored by your 3PL vendor. Each lot represents the receipt of some quantity of an external SKU at a specific time. Your 3PL vendor must provide inventory advice to you regarding inventory levels. Your 3PL vendor may create up to 100 external lots per call.

To create external lots, use API call Inventory.ExternalLot.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 '' \
    -H 'Content-Type: application/json' \
    -H 'apikey: YOUR_APIKEY_GOES_HERE' \
    -d '{
              "date_created": "2015-01-01T00:00:00Z",
              "received_quantity": 10,
              "vpc": "ABC"
              "date_created": "2015-01-01T00:00:00Z",
              "received_quantity": 1,
              "vpc": "XYZ"
Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk