Fulfillment and Shipping Request Objects

Shipping Request Data Model

A Shipping Request (also known as a shipment) in Pipe17 represents a request to a logistics provider to fulfill an order. It's created by the Order Routing Engine when an order is processed and contains all the information needed for a fulfillment provider to ship items to a customer.

Shipping Request Key Fields

Required Fields for Creation

Only 2 fields are required to create a shipping request:

• extOrderId: Customer-friendly ID on the order object (required)

• shippingAddress: Destination address for shipment (required - see Address structure below)

All other fields are optional and can be provided based on your specific fulfillment needs.

Identification Fields

• shipmentId: Unique identifier for the shipping request within Pipe17 (system-generated)

• extShipmentId: Customer-friendly reference to this shipping request on the originating vendor

• extReferenceId: Customer-friendly reference to this shipping request on the destination vendor

• extReferenceUrl: Direct link to this shipping request on the destination vendor

• extOrderId: Customer-friendly ID on the order object (required)

• extOrderApiId: External System Order API ID

• orderId: Pipe17 Internal Order's orderId that this shipping request is associated with

• version: Document version number for concurrency control and tracking updates

Status Fields

• status: Current status of the shipping request. Possible values include:

  • pendingInventory: Waiting for inventory to become available

  • pendingShippingLabel: Waiting for shipping labels

  • readyForFulfillment: Ready to be sent to the fulfillment provider

  • sentToFulfillment: Has been sent to the fulfillment provider

  • fulfilled: All items have been fulfilled

  • partialFulfillment: Some items have been fulfilled

  • canceled: Shipping request has been canceled

  • canceledRestock: Canceled with inventory restocked

  • failed: Processing failed

• extStatus: Shipment status on the external system (for synchronization with fulfillment providers)

• cancellationStatus: Status of cancellation if applicable (pending, accepted, rejected)

• canceledAt: The cancellation date

• canceledBy: The cancel requester ID

• canceledByType: The cancel requester ID type (user, integration, apikey)

• sentToFulfillmentAt: Timestamp when the request was sent to fulfillment

• fulfilledAt: Timestamp when the shipment was fully fulfilled (system-generated)

Warehouse Operations Status

Pick/Pack/Ship Tracking

These fields track the warehouse fulfillment process from picking items to shipping:

• pickStatus: Current warehouse operation status

  • pending: Items not yet picked from warehouse

  • picked: Items picked from warehouse shelves

  • packed: Items packed and ready to ship

  • shipped: Items shipped from warehouse

• pickedAt: Timestamp when items were picked from warehouse

• packedAt: Timestamp when items were packed

• shippedAt: Timestamp when items were shipped from warehouse

Workflow: pending → picked → packed → shipped

Automation and Routing

• autoEngUpdateStatus: Status indicating whether the automation engine may update the entity

• autoEngUpdateStatusUpdatedAt: When the autoEngUpdateStatus was last updated

• reused: Indicates if the shipment's extShipmentId is being reused in another one

• skipLocation: Flag to indicate the location in this SR should be skipped during rerun-routing

• excludeFromReuse: Flag to indicate whether ID of this SR can be reused or not

Shipping Information

• shippingAddress: Object containing shipping address details

  • firstName, lastName, company

  • address1 (required within address object), address2

  • city, stateOrProvince, zipCodeOrPostalCode

  • country (required within address object)

  • phone, email

  • addressType: Type of address (optional)

    • residential: Residential address

    • commercial: Business/commercial address

    • institutional: Institution (school, hospital, etc.)

    • military: Military base

    • pobox: PO Box

    • other: Other address type

Shipping Method Priority

The shipping method is determined by the following priority order:

1st Priority (Highest):

• shippingCode: Shipping code - if provided, this takes highest priority and overrides carrier and class

2nd Priority:

• shippingCarrier: Shipping carrier to be used (optional, used with shippingClass)

• shippingClass: Shipping service level (optional, used with shippingCarrier)

• When both carrier and class are provided together, they form the 2nd priority shipping method

3rd Priority (Fallback):

• Location's default shipping method (used when neither code nor carrier+class are provided)

Other Shipping Fields:

• shippingPrice: Shipping price

• shippingNote: Shipping note

• shippingLabels: Array of shipping labels

• shippingMethodMapping: Enable shipping method mapping

Timing Fields

• expectedDeliveryDate: First priority to be respected

• expectedShipDate: Expected ship date

• shipAfterDate: Ship after date

• shipByDate: Ship by date

• shipCancelByDate: Ship cancel by date

• holdUntil: Date until which the shipping request should be held

• orderCreateTime: Create time of linked order

Line Items

• lineItems: Array of items in the shipping request

  • sku: Item SKU

  • uniqueId: Item unique ID within the shipment

  • quantity: Item quantity

  • shippedQuantity: Item shipped quantity

  • name: Item name

  • itemPrice: Item price

  • itemDiscount: Item discount

  • weight: Item weight

  • quantityUnit: Units of measurement (each, can, bottle, etc.)

  • bundleSKU: Reference to bundle for bundle components

  • bundleQuantity: Quantity of item in bundle for bundle components

  • bundleUPC: Reference to bundle for bundle components

  • upc: Item UPC

  • trackedAtSourceChannel: Whether tracking is handled at the source channel

  • customFields: Array of custom fields (name-value pairs)

Order Information

• orderType: Type of order that initiated this shipping request (sales, transfer, purchase)

• orderSource: Actual order source (e.g., Walmart, Etsy)

• orderSourceType: Order type (online, pos, wholesale, edi, other, b2b)

• currency: Currency code (inherited from order)

Fulfillment Configuration

• fulfillmentIntegrationId: Destination of this shipping request (the integration handling fulfillment)

• locationId: ID of location defined in organization

• overfulfillPolicy: Overfulfill policy

  • strict: Reject overfulfillment

  • report: Allow overfulfillment but flag for review

  • approved: Allow overfulfillment without flagging

Miscellaneous

• giftNote: Shipping gift note

• incoterms: International Commercial Terms

• privacyPolicy: Privacy policy array

• tags: Tags assigned to the shipping request

• customFields: Array of custom fields (name-value pairs)

• internal: Object for internal information

• sourceDoc: Vendor source document

• timeline: Array of timeline entries tracking updates to the shipping request

• exceptions: Types of exceptions related to the shipping request

• exceptionCategories: References to categories of exceptions related to the shipping request

System Fields

• createdAt: When the shipping request was created in Pipe17 (system-generated)

• updatedAt: When the shipping request was last updated in Pipe17 (system-generated)

• orgKey: Organization this object belongs to (system-generated, multi-tenant isolation)

• integration: Reference to integration that created the shipping request

• orderIntegration: Reference to integration that created the order tied to the shipping request

Shipping Request Uniqueness

Within an organization, the following combinations must be unique:

• extShipmentId (when defined)

• extReferenceId + fulfillmentIntegrationId (when extReferenceId is defined)

Fulfillment Data Model

A Fulfillment in Pipe17 represents a record of a completed shipping request processing and delivery attempt. It's created when a fulfillment provider confirms that a shipping request has been processed and provides tracking information.

Fulfillment Key Fields

Required Fields for Creation

Required fields vary by fulfillment type:

For accepted fulfillments (normal successful fulfillment):

• shipmentId: Internal Pipe17 ID of the shipping request (required)

• trackingNumber: Array of tracking numbers (required)

• lineItems: Items being fulfilled (required)

For rejected or void fulfillments:

• shipmentId: Internal Pipe17 ID of the shipping request (required)

• lineItems: Items being fulfilled (required)

• trackingNumber: NOT required (fulfillment rejected or voided before shipping)

Identification Fields

• fulfillmentId: Unique identifier for the fulfillment within Pipe17 (system-generated)

• shipmentId: Internal Pipe17 ID of the shipping request this fulfillment is for (required)

• extFulfillmentId: Reference to fulfillment on external system (vendor)

• extOrderId: External customer-friendly ID

• orderId: Pipe17 Internal Order's ID

Status and Type

• fulfillmentType: Type of fulfillment

  • accepted: Successfully fulfilled with tracking information (default)

  • rejected: Fulfillment rejected by warehouse (no tracking needed)

  • void: Void/cancel existing fulfillment (no tracking needed)

• autoEngUpdateStatus: Status indicating whether the automation engine may update the entity

Fulfillment Type Use Cases:

• accepted: Normal successful fulfillment with tracking numbers - items were picked, packed, and shipped

• rejected: Warehouse rejected the fulfillment request (e.g., out of stock, damaged inventory, address issues) - no tracking numbers needed

• void: Void or cancel an existing fulfillment (e.g., customer canceled after shipping started) - no tracking numbers needed

Fulfillment Grouping

Batch Fulfillment Support

• groupId: Group ID for batching multiple fulfillments together

  • Use when multiple shipments need to be tracked as a single fulfillment group

  • Helpful for complex orders split across multiple packages

• groupLineItems: Array of line items associated with fulfillment group

  • Tracks which items belong to the fulfillment group

  • Enables group-level fulfillment tracking

Shipping Information

• actualShipDate: Actual ship date

• expectedArrivalDate: Expected arrival date

• trackingNumber: Array of tracking numbers (required for accepted type, optional for rejected and void)

• trackingURLs: Array of tracking URLs

• shippingCarrier: Shipping carrier

• shippingClass: Shipping service level

• shippingCharge: Shipping charge

• billOfLading: Bill of lading reference

• ucc128: UCC-128 code

• ssccCode: SSCC code

• sacCode: SAC code

Physical Attributes

• weight: Weight

• weightUnit: Weight unit (lb, oz, kg, g)

• length, width, height: Package dimensions

• dimensionsUnit: Dimensions unit of measurement (cm, in, ft)

Line Items

• lineItems: Array of items in the fulfillment (required)

  • sku: Item SKU

  • uniqueId: Item unique ID (to be matched with shipment line item)

  • quantity: Item quantity

  • name: Item name

  • weight: Item weight

  • quantityUnit: Units of measurement (each, can, bottle, etc.)

  • upc: Item UPC

  • lotNumber: Item lot number provided by fulfillment channel

  • expirationDate: Item expiration date provided by fulfillment channel

  • serialNumbers: Item serial numbers provided by fulfillment channel

  • bundleSKU: Matching bundle SKU when available

  • bundleQuantity: Matching bundle quantity when available

  • bundleUPC: Reference to bundle for bundle components

  • trackedAtSourceChannel: Whether tracking is handled at the source channel

  • customFields: Array of custom fields (name-value pairs)

Acknowledgement Tracking for Downstream Systems

• acknowledgements: Array of acknowledgement records tracking when downstream systems (ERP, OMS) acknowledge receipt of fulfillment

  • source: System that acknowledged (erp or oms)

  • acknowledgedAt: Timestamp when acknowledged

  • acknowledgementData: Custom acknowledgement data object

Acknowledgement Sources:

• erp: ERP system acknowledgement

• oms: Order Management System acknowledgement

Use Case: Track whether downstream business systems have successfully received and processed the fulfillment information, ensuring data synchronization across your technology stack.

Miscellaneous

• tags: Tags assigned to the fulfillment

• customFields: Array of custom fields (name-value pairs)

• internal: Object for internal information

• sourceDoc: Vendor source document

• timeline: Array of timeline entries tracking updates to the fulfillment

• exceptions: Types of exceptions related to the fulfillment

• exceptionCategories: References to categories of exceptions related to the fulfillment

• trackedAtSourceChannel: Whether tracking number were issued by source channel

System Fields

• createdAt: When the fulfillment was created in Pipe17 (system-generated)

• updatedAt: When the fulfillment was last updated in Pipe17 (system-generated)

• orgKey: Organization this object belongs to (system-generated, multi-tenant isolation)

• integration: Reference to integration that created the fulfillment

• orderIntegration: Reference to integration that created the order tied to the fulfillment

• shipmentIntegration: Reference to integration that created the shipment tied to the fulfillment

• orderType: Type of Pipe17 Internal Order (sales, transfer, purchase)

• locationId: Location ID of the fulfillment

Relationship Between Shipping Requests and Fulfillments

Creation Flow

1. Order Routing: When an order is processed by the Order Routing Engine, one or more shipping requests are created based on routing rules.

2. Shipping Request Processing: The shipping request is sent to the fulfillment provider specified by the fulfillmentIntegrationId.

3. Warehouse Operations (NEW): The warehouse processes the shipment through pick/pack/ship stages:

   • pickStatus: pending → Items not yet picked

   • pickStatus: picked → Items picked from shelves

   • pickStatus: packed → Items packed in boxes

   • pickStatus: shipped → Items shipped from warehouse

4. Fulfillment Creation: When the fulfillment provider processes the shipping request, they create a fulfillment record in Pipe17 with tracking information.

5. Status Updates: The shipping request status is updated to fulfilled or partialFulfillment based on the fulfillment.

6. Acknowledgement (NEW): Downstream systems (ERP, OMS) acknowledge receipt of the fulfillment data.

Key Relationships

• One-to-Many: An order can have multiple shipping requests (e.g., split shipments).

• One-to-One or One-to-Many: A shipping request typically has one fulfillment, but may have multiple fulfillments for partial fulfillment scenarios:

  • Example: Shipment with 10 items → First fulfillment ships 6 items (status: partialFulfillment) → Second fulfillment ships 4 items (status: fulfilled)

• Direct Reference: A fulfillment directly references its shipping request via the shipmentId field.

• Order Reference: Both shipping requests and fulfillments reference the same order via the orderId field.

• Location Relationship: Both reference locationId to track the warehouse/location handling the fulfillment.

• Product Relationship: Line items in both entities reference products via sku field.

• Integration Chain: The integration, orderIntegration, and shipmentIntegration fields track which systems handled each part of the process:

  • orderIntegration: Integration that created the order (e.g., Shopify, Amazon)

  • integration (on shipment): Integration that created the shipping request (usually same as orderIntegration or internal routing)

  • fulfillmentIntegrationId: Integration that will fulfill the order (e.g., ShipStation, ShipHero)

  • integration (on fulfillment): Integration that created the fulfillment record (usually the WMS)

Status Transitions

Shipping Request Status Flow

1. Shipping Request Creation: Status starts as readyForFulfillment or pendingInventory.

2. Inventory Check: If inventory is available, status becomes readyForFulfillment; otherwise, pendingInventory.

3. Sent to Fulfillment: When sent to the fulfillment provider, status becomes sentToFulfillment.

4. Warehouse Operations (NEW): While in sentToFulfillment, the pickStatus tracks warehouse progress:

   • pickStatus: pending → Awaiting pick

   • pickStatus: picked → Items picked (timestamp: pickedAt)

   • pickStatus: packed → Items packed (timestamp: packedAt)

   • pickStatus: shipped → Items shipped (timestamp: shippedAt)

5. Fulfillment Creation: When fulfillment is created, shipping request status becomes fulfilled or partialFulfillment.

6. Cancellation: If canceled, status becomes canceled or canceledRestock (if inventory is restocked).

7. Failure: If processing fails, status becomes failed.

Pick/Pack/Ship Status Flow

Status Relationships:

• Shipment status: sentToFulfillment

  • pickStatus: pending → Items awaiting warehouse pick

  • pickStatus: picked → Items picked from warehouse

  • pickStatus: packed → Items packed in boxes

  • pickStatus: shipped → Items shipped from warehouse

• Shipment status: fulfilled → Fulfillment record created with tracking

Practical Applications

Shipping Request Management

• Creation: Shipping requests are created automatically by the Order Routing Engine or manually through the UI.

• Warehouse Tracking: Use pickStatus to track warehouse operations:

  • Monitor which shipments are awaiting pick

  • Track pick/pack efficiency with timestamps

  • Identify bottlenecks in warehouse operations

  • Automated workflows can trigger based on status changes

• Cancellation: Shipping requests can be canceled, with an option to restock inventory.

• Routing: The Order Routing Engine determines which location and fulfillment provider to use based on configured rules.

Fulfillment Tracking

• Tracking Information: Fulfillments contain tracking numbers and URLs for shipment tracking.

• Shipping Confirmation: Fulfillments serve as confirmation that items have been shipped.

• Delivery Estimation: Expected arrival dates help manage customer expectations.

• Type-Specific Handling:

  • Accepted: Normal fulfillment with tracking - notify customer with tracking info

  • Rejected: Warehouse rejected fulfillment - trigger restock and reroute to alternate location

  • Void: Cancel fulfillment after shipment - handle returns workflow

Inventory Management

• Commitment: When a shipping request is created, inventory is committed for the items.

• Warehouse Operations Impact: Inventory states change as items move through pick/pack/ship:

  • pickStatus: pending → Inventory committed

  • pickStatus: picked → Inventory still committed, physically picked

  • pickStatus: packed → Inventory ready for shipment

  • pickStatus: shipped → Inventory in transit (when fulfillment created)

• Restocking: When a shipping request is canceled with the restock option, inventory is returned to available stock.

• Fulfillment Impact: When a fulfillment is created, committed inventory is reduced from on-hand inventory.

Acknowledgement Workflow

Ensuring Downstream System Synchronization

1. Fulfillment created by WMS and sent to Pipe17

2. Pipe17 processes and validates fulfillment

3. ERP/OMS systems poll for new fulfillments

4. ERP/OMS acknowledges receipt via /fulfillments/acknowledge endpoint

5. Acknowledgement timestamp recorded in acknowledgements array

6. Use acknowledgement status to ensure all systems are synchronized

Use Cases:

• Monitor unacknowledged fulfillments to detect integration issues

• Ensure accounting systems have received fulfillment data

• Track data flow across technology stack

• Trigger alerts for delayed acknowledgements

Fulfillment Grouping

Batch Fulfillment Operations

Use groupId to track multiple related fulfillments:

• Large orders split across multiple packages

• Orders fulfilled from multiple locations

• Subscription box shipments with multiple fulfillment dates

• Track group fulfillment completion status

Example: Order with 20 items split into 3 packages:

• Fulfillment 1: groupId: "order-123-group", 8 items, tracking: "1Z111"

• Fulfillment 2: groupId: "order-123-group", 7 items, tracking: "1Z222"

• Fulfillment 3: groupId: "order-123-group", 5 items, tracking: "1Z333"

Exception Handling

• Failed Shipping Requests: If a shipping request fails, exceptions are created to alert users.

• Fulfillment Mismatches: If a fulfillment doesn't match its shipping request, exceptions are created.

• Resolution: Exceptions can be resolved by canceling and recreating shipping requests or by other corrective actions.

Key Workflows

Order Routing to Fulfillment

1. Order is received and processed by Pipe17

2. Order Routing Engine creates shipping request(s) based on routing rules

3. Shipping request is sent to the fulfillment provider

4. Fulfillment provider processes the request and creates a fulfillment

5. Fulfillment includes tracking information for customer notification

Pick/Pack/Ship Workflow

Complete Warehouse Operations Flow

1. Shipment Created

   • Status: readyForFulfillment

   • pickStatus: pending

2. Sent to Warehouse

   • Status: sentToFulfillment

   • pickStatus: pending

   • Warehouse receives pick list

3. Items Picked

   • pickStatus: picked

   • pickedAt: timestamp recorded

   • Items physically picked from warehouse shelves

4. Items Packed

   • pickStatus: packed

   • packedAt: timestamp recorded

   • Items packed in shipping boxes/containers

5. Items Shipped

   • pickStatus: shipped

   • shippedAt: timestamp recorded

   • Packages shipped from warehouse

6. Fulfillment Created

   • Status: fulfilled or partialFulfillment

   • Tracking numbers provided

   • Customer notified

Benefits:

• Real-time visibility into warehouse operations

• Identify bottlenecks (slow picking, packing issues)

• Calculate pick/pack/ship times for performance metrics

• Trigger automated notifications at each stage

Partial Fulfillment Workflow

Handling Multiple Fulfillments for Single Shipment

1. Shipment Created with 10 items total

   • Status: readyForFulfillment

   • lineItems: 10 items

2. Sent to Warehouse

   • Status: sentToFulfillment

3. Warehouse Can Only Fulfill 6 Items

   • Remaining 4 items are out of stock or backordered

4. First Fulfillment Created with 6 items

   • Fulfillment 1: 6 items, tracking: "1Z111"

   • Shipment status: partialFulfillment

   • Customer notified of partial shipment

5. Remaining Inventory Available

   • 4 items now in stock

6. Second Fulfillment Created with 4 items

   • Fulfillment 2: 4 items, tracking: "1Z222"

   • Shipment status: fulfilled

   • Customer notified of second shipment

Use Cases:

• Backorder scenarios

• Split fulfillment from multiple warehouses

• Partial inventory availability

• Different ship dates for different items

Rejected Fulfillment Workflow

Handling Warehouse Rejections

1. Shipment Sent to Warehouse

   • Status: sentToFulfillment

2. Warehouse Cannot Fulfill

   • Reasons: Out of stock, damaged inventory, address issues, etc.

3. Rejected Fulfillment Created

   • fulfillmentType: rejected

   • trackingNumber: NOT provided (no shipping occurred)

   • customFields: Add rejection reason

   { "shipmentId": "ship-123", "fulfillmentType": "rejected", "lineItems": [...], "customFields": [ {"name": "rejectionReason", "value": "Out of stock"}, {"name": "rejectionDate", "value": "2025-11-04"} ] }

4. Shipment Status Updated

   • Status may remain sentToFulfillment or change to failed

5. Next Steps

   • Restock inventory if needed

   • Reroute to alternate location

   • Cancel order if no alternate fulfillment available

   • Notify customer of delay

Void Fulfillment Workflow

Canceling After Fulfillment Created

1. Fulfillment Created and Acknowledged

   • fulfillmentType: accepted

   • Tracking numbers provided

   • Customer notified

2. Customer Cancels Order (or other issue)

   • Cancellation received after fulfillment

3. Void Fulfillment Created/Updated

   • fulfillmentType: void

   • Original tracking numbers retained (for returns)

   • Shipment may need to be intercepted if possible

4. Handle Returns Process

   • Wait for package to be returned

   • Process refund

   • Restock inventory when returned

Acknowledgement Workflow

ERP/OMS Acknowledgement Process

1. Fulfillment Created by WMS

   • Fulfillment sent to Pipe17

2. Pipe17 Processes fulfillment

   • Validation checks

   • Inventory updates

3. ERP System Polls for new fulfillments

   • Query: GET /fulfillments?orderIntegrationAcknowledged=false

4. ERP Processes fulfillment data

   • Updates accounting

   • Updates inventory records

   • Processes revenue recognition

5. ERP Acknowledges Receipt

   • POST /fulfillments/acknowledge

   { "fulfillmentId": "fulfill-123", "source": "erp", "acknowledgementData": { "erpOrderId": "ERP-456", "processedBy": "accounting-system" } }

6. Acknowledgement Recorded

   • acknowledgements array updated with timestamp

   • acknowledgements[]: {source: "erp", acknowledgedAt: "2025-11-04T15:30:00Z"}

Cancellation and Restocking

1. User cancels a shipping request in Pipe17

2. If "Restock items" is checked, inventory is returned to available stock

3. If the shipping request was already sent to the fulfillment provider, the user must also cancel it there

4. The shipping request status is updated to canceled or canceledRestock

Manual Shipping Request Creation

1. User clicks "New shipping request" on an order

2. User selects location, shipping method, and items to include

3. Shipping request is created with status readyForFulfillment

4. The request is sent to the fulfillment provider based on the selected location

Troubleshooting Failed Shipping Requests

1. If a shipping request fails, its status becomes failed

2. Exceptions are created to indicate the reason for failure

3. User can check the Events page for error messages

4. User can cancel the failed request and create a new one\

API Operations Reference

Shipping Request REST API

Batch Limits: Maximum 10 shipments can be created in a single batch request.

Common Query Parameters:

• shipmentId, extShipmentId, orderId, extOrderId

• status, pickStatus (NEW)

• locationId, fulfillmentIntegrationId

• since, until, updatedSince, updatedUntil

Fulfillment REST API

Batch Limits: Maximum 10 fulfillments can be created in a single batch request.

Common Query Parameters:

• fulfillmentId, shipmentId, extFulfillmentId, orderId, extOrderId

• fulfillmentType, groupId (NEW)

• locationId, integration, orderIntegration

• acknowledgedBy, orderIntegrationAcknowledged

• since, until, updatedSince, updatedUntil

Quick Reference Tables

Shipping Request Status Values

Pick Status Values

Fulfillment Type Values

Shipping Method Priority

Required Fields by Entity

Overfulfill Policy Values

Need Help?

If you need additional assistance:

• Use Ask Pippen, our AI agent, located at the top of the app page.

• Submit a support request with as much relevant detail as possible. Learn how to submit a request.

• For urgent issues, email us directly at support@pipe17.com.

We're here to help you succeed with your operations.