API Based Connection (Legacy)

PLEASE NOTE THIS IS LEGACY WAY OF INTEGRATING WITH PIPE17.

The steps described below in this document explains how one can build an API-based integration.

Resources

Pipe17 API Doc: https://apidoc.pipe17.com
Support Portal: https://support.pipe17.com

Key Concepts

Location

Typically, a location object in Pipe17 represents a warehouse location in the 3PL. The integration using this location for fulfillment interprets the meaning of the location. An integration can one location for every physical location in the 3PL, or one can create a single location in Pipe17 representing all locations in the 3PL.

Orders are routed this this location, and inventory is associated to this location.

Orders

An order object is what Pipe17 gets from the ecommerce system. It holds the entire representation of the original order within Pipe17 including all financial data. Logistic connectors does not have access to orders. You can find the order data model here. The integration connecting to the order source is responsible to pull the order data from the ecommerce system and translate into this order data model.

Sending routed orders to 3PL via custom integration

This is a high level illustration of the order travels from the platform to the external 3PL. It shows how the built-in (native) 3PL integrations works as well as how a custom 3PL integration would work.

Shipping Request (aka Shipments)

Shipping Request is how Pipe17 allocates orders to a particular location / logistic partner for fulfillment. Customer uses the Order Routing Engine to define routing rules. The engine evaluates those rules against the eligible order to route them. The outcome of the process is a Shipping Request that largely contains the following data:

Fulfillment Location to which the full or part of the order is assigned
Line items assigned to the location
Shipping address
Recommended shipping method

The Shipping Request data model can be found here.

This is the main entity that any logistic system should work with. The shipments have multiple status. The main one is “Ready for Fulfillment” or “readyForFulfillment” within the API. This is the status when evaluating if the shipment should be processed.

The logistic partner using the API based integration would use the Shipping Request List API to find eligible requests for fulfillment.

Typically, the logistic partner integration would use the list API to get all Shipping Request updatedSince using date/time when you polled the platform last and status readyForFulfillment and locationId referring the Pipe17 location ID(s) this integration is servicing.

The integration can fetch more data for the individual Shipping Request returned by this call, ensure they are ready to be consumed.

The key value to reference when posting by fulfillments is shipmentId. Integration needs to store the checkpoint of last successful poll to use with the next poll.

Once the shipment has been processed by the logistic partner integration, it should update the Shipping Request to “Sent To Fulfillment” or “sentToFulfillment”. This tells the platform that the shipping request has been picked by the logistic partner for fulfillment.

Reporting back fulfillment data from 3PL via custom integration

This is a high level illustration of the fulfillment/tracking data travels from the external 3PL to the platform. It shows how the built-in (native) 3PL integrations works as well as how a custom 3PL integration would work.

Fulfillment

Once the logistic partner picks, packs and ships, and has a tracking number to report, the parter integration has to create a Fulfillment object in the platform using the create Fulfillment API, against the reference found in the Shipping Request.

Line items shipped, their tracking number(s), and the corresponding shipmentId. shipmentId is required to create the Fulfillment, and that's how the platform knowns the correlation with Shipping Request.

The Fulfillment data model can be found here.

Fulfillments are considered immutable within the platform, i.e. once created cannot be updated. So integration should not create fulfillment unless the fulfillment has been finalized. No further updates are allowed. Fulfillment object tells the platform whether part or all of the requested line items have been fulfilled, and the corresponding tracking number(s). The platform will automatically transition the status of the Shipping Request and the Order based on the fulfillment coming back to fulfilled or partial fulfillment.

Integration can report order cancelation by creating a Fulfillment with type rejected. The platform capture this data and shows it to the user in the UI. User can then reroute the order to some other location.

Inventory

Inventory object is what is used for Pipe17 to route orders and also update the selling channel on availability.

Testing API-based Connection

Overview

You can click on the image below

Processing Shipment

Create a location within Pipe17 manually that represents your warehouse
If you are planning to use webhooks. Make sure you are listening to shipments webhook.
Create an order within Pipe17, can be ingested from a ecommerce channel or created via API, ensure it has 2 line item
Within the order detail page on Pipe17, manually create a shipment for one of the line item and make sure the location selected was what you created above
Create another shipment that is for the other line item and NOT assigned to the location you created
Make sure your logic is checking for the following
- locationId = what you created
- status = readyForFulfillment
Process the shipment within your system
Update the shipment status to “sentToFulfillment” after you have ingested

Processing Fulfillment

Make sure the fulfillment being sent back to Pipe17 line item matches the shipment uniqueId and SKU. We use this information to ensure proper fulfillment handling.
Make sure that the fulfillment has been finalized. Within Pipe17, fulfillment is considered immutable, so no updates can happen after creation.

Rejecting Fulfillment

There is a concept of reject fulfilment which would allow Pipe17 to understand what can and can't be fulfilled. You make this call similar to a normal fulfillment call but the fulfillmentType is "rejected" with the right line item id is getting rejected.

Processing Inventory

Pipe17 has the concept of Inventory ledger, all inventory update call should be made by POST to the inventory endpoint.

curl --location 'https://api-v3.pipe17.com/api/v3/inventory' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Pipe17-Key: ••••••' \
--data '{
  "event": "ingest",
  "ptype": "wms",
  "sku": "EXAMPLESKU",
  "locationId": "Provided by Merchant",
  "onHand": "<integer>",
  "committed": "<integer>"
}'