Chapter 5: Implementing Orders & Fulfillment Workflow

Orders are the central piece in Pipe17, you can learn more about Orders here.

Here is a quick view of the Order flow through Pipe17.

The typical workflow of an Order is as follows:

The selling channel integration pulls Order into Pipe17 from a selling channel (Ex: Shopify) using the selling channels's order fetch API and then creates order in Pipe17 using order create API
- The selling channel integration can be built-in or custom
Pipe17 routes the order based on Order Routing rules
Pipe17's Order Routing Engine creates a Shipping Request for line items routed to a certain Location based on the rules
The fulfillment channel integration pushes Shipping Request from Pipe17 to the Fulfillment channel (Ex: ShipBob)
- The fulfillment channel integration can be built-in or custom
- If fulfillment channel integration is built-in, Pipe17 pushes the Shipping Request to the external fulfillment (WMS/3PL) system using external systems APIs to create order
- If fulfillment channel integration is custom, the custom integration has to look for all eligible Shipping Requests for Locations owned by this integration, read them from Pipe17 using Shipping Request LIST & GET APIs and push them to the external system
The fulfillment channel integration brings Fulfillment (aka Shipment) data into Pipe17 from a Fulfillment channel (Ex: ShipBob)
- If fulfillment channel integration is built-in, Pipe17 scans the external system for any new fulfillment, and if found brings that data into Pipe17 by creating a Fulfillment object against the Shipping Request using Fulfillment create API
  - NOTE: Fulfillments in Pipe17 are immutable. They cannot be updated once created. So custom integration should create the Fulfillment only when all the necessary data is available.
- If fulfillment channel integration is custom, the custom integration has to look for all new Fulfillments in the external system, fetch their data and create Fulfillment in Pipe17 using Fulfillment create API
The selling channel integration pushes the Fulfillment data to the external channel (Ex: Shopify) by using Pipe17's Fulfillment LIST & GET APIs, and then pushing them to the external system.
Push Fulfillment back to the original Sales channel

We will look at how each step is accomplished.

Step 1: Order Routing

Please follow the guide here to setup Order routing such that the Order is sent to the custom connection you have added in your Org.

Step 2: Ingest or Create Orders

Besides connecting a Sales channel, Orders can also be imported into Pipe17 manually by uploading a CSV or using a JSON. For the purposes of this implementation we will import using the JSON below:

{
"billingAddress": {
"company": "Test2",
"country": "US"
},
"customer": {
"company": "Test2",
"extCustomerId": "C0000007"
},
"extOrderCreatedAt": "2025-01-06T00:00:00.000Z",
"extOrderId": "SB0001",
"extOrderUpdatedAt": "2025-01-06T11:49:19.650Z",
"lineItems": [
{
"uniqueId": "SS-LI-001",
"sku": "SFG-THR-BAB-ARI-PER-ONE-CHR-001",
"quantity": 1,
"itemPrice": 20,
"itemDiscount": 0,
"requiresShipping": true,
"taxable": false,
"requiresShippingSource": "integration",
"quantityUnit": "each"
}
],
"orderDiscount": 0,
"orderNote": "-",
"orderSource": "Acumatica",
"orderTax": 0,
"shipAfterDate": "2025-01-06T00:00:00.000Z",
"shippingAddress": {
"company": "Test2",
"country": "US",
"address1": "Middlefield Rd",
"city": "Mountain View",
"firstName": "Pipe17",
"lastName": "Tester",
"stateOrProvince": "CA",
"zipCodeOrPostalCode": "94555"
},
"status": "draft",
"subTotalPrice": 20,
"totalPrice": 20
}

NOTE: Remember the update the "extOrderId": "SB0001" for each new Order you create.

Step 3: Get Shipping Requests

A Shipping Request is now "routed" to the custom connection - meaning the Shipping Request has been created by Order Routing Engine, assigned to the custom connection location. You can learn more about Shipping Requests here.

At this point the custom connection code can poll for Shipping Requests and pull it in.

Shipping Request in Pipe17

The custom connection can poll for Shipping Requests assigned to its connection location & id by calling the List Shipping Requests API. Once again this can be filtered by updatedSince timestamp so we only pull the latest Shipping Requests available.

Orders in Sample App

Ideally all of this happens in background jobs that run regularly, but for illustration purposes there is a sample App in the reference implementation.

You can view this implementation in the orderService.js file.

Clicking on the Pull Orders from Pipe17 will pull all available Shipping Requests for this connection with a fixed set of statuses. Typically you would only want to pull for status 'readyForFulfillment' but based on your business case other statuses might be relevant.

Once an Order is successfully created in ShipBob, the connection code will do another call to Pipe17 - this time to update the status of the Shipping Request as 'sentToFulfillment' along with the id received from ShipBob set as the 'extReferenceId'

Based on your business case you might want to update the status only after ShipBob does a 'pick' of the Order. But in general updating the status of the Shipping Request in Pipe17 is important to notify the customer of the Order status and also Pipe17 might mark it as Sent Order Failure after specific amount of time passes.

Step 4: Locate Fulfillments in ShipBob

The next step for the connection is to poll for available Fulfillments from ShipBob.

You can view implementation related to fulfillments in the fulfillmentService.js file.

You can trigger this by clicking "Pull Fulfillments" on the sample App.

Click on "View Fulfillments" button to see the available Fulfillments for the specific Order.

Step 5: Push Fulfillments to Pipe17

The connection should now push available Fulfillments to Pipe17. Clicking on "Push to Pipe17" will trigger this action. The Fulfillment will then become available on Pipe17.

This completes an end-to-end workflow of an Order moving from Sales to Pipe17, from Pipe17 to 3PL channel, and back from 3PL channel to Pipe17.