Understanding the Pipe17 Data Model

Learn more about Data flow in this course.

Core Entity Types

Orders

Orders represent customer purchases and form the core of the Pipe17 system. Each order tracks product, payment, routing, and fulfillment details.

Key Properties:

• orderId – Internal Pipe17 identifier

• extOrderId, extOrderApiId, extOrderUrl – External system identifiers and API references

• status – Lifecycle state of the order (see full lifecycle below)

• routingStatus – Tracks routing progress (pending, ready, acknowledged, etc.)

• autoEngUpdateStatus, autoEngUpdateStatusUpdatedAt – Tracks automation workflows

• isMultiDestination – Indicates multi-destination fulfillment

• paymentStatus, fulfillmentStatus – Parallel financial and logistics states

• holdUntil – Holds order processing until a specified time

• shipByDate, shipAfterDate, shipCancelByDate – Shipping constraint dates

• payments, discounts, additionalCharges, refunds – Financial details

• customer – Object containing firstName, lastName, email, phone, and address

• timeline – Audit trail of order changes

Lifecycle Statuses:
draft → new → onHold → toBeValidated → reviewRequired → readyForFulfillment → sentToFulfillment → partialFulfillment → fulfilled → inTransit → partialReceived → received → canceled → returned → refunded → archived → closed

Routing Status Values:
disabled, pending, ready, acknowledged, failed, excluded, pendingInventory

Shipments

Shipments track the fulfillment of orders at one or more locations.

Key Properties:

• shipmentId – Unique shipment identifier

• orderId – Linked order reference

• locationId – Fulfillment location

• status – Shipment lifecycle status

• version – Sequential counter for multiple shipment revisions

• cancellationStatus – Tracks canceled or restocked shipments

• overfulfillPolicy – Defines over-shipment handling

• shippingLabels[] – Generated labels with URLs or identifiers

• timeline – Records shipment events

Shipment Lifecycle:
new → pendingInventory → pendingShippingLabel → reviewRequired → readyForFulfillment → sentToFulfillment → partialFulfillment → fulfilled → canceled → canceledRestock → failed → onHold

Fulfillments

Fulfillments represent executed shipments with tracking and packaging details.

Key Properties:

• fulfillmentId – Unique identifier

• shipmentId – Linked shipment reference

• fulfillmentType – accepted, rejected, or voided

• acknowledgedBy, acknowledgement – Tracks system-level acknowledgment

• actualShipDate, expectedArrivalDate – Delivery schedule details

• weight, height, length, width, and respective unit fields

• ssccCode, sacCode, ucc128, billOfLading – Supply chain barcodes

• timeline – Change log

Products

Products define items available for order and fulfillment.

Key Properties:

• sku, name, description – Core identifiers and details

• types – simple, bundle, bundleItem, child, parent

• inventoryNotTracked – Indicates non-tracked SKUs

• hideInStore – Controls product visibility

• mappedProduct – Cross-system product linkage

• partId – Manufacturer part number

• harmonizedCode, countryOfOrigin – Customs and compliance attributes

• variantOptions, bundleItems[] – Product hierarchies

Inventory

Inventory tracks stock quantities across physical and virtual locations.

Key Properties:

• sku, locationId – Product-location linkage

• onHand, available, availableToPromise, incoming, future, committedFuture, unavailable, commitShip, commitXfer – Quantity states

• type – virtual or physical

• ptype – Inventory source type (wms, ims, oms, portal)

• vendorSKU – Vendor-specific SKU reference

• timeline – Ledger of stock changes

Inventory Event Types (19 total):
ingest, adjust, touch, POSOrder, virtualCommit, ship, shipCancel, shipCancelRestock, fulfill, futureShip, release, futureShipCancel, xferout, xferfulfill, xferin, receive, return

Locations

Locations define physical or virtual fulfillment and storage points.

Key Properties:

• locationId, name, address, status

• fulfillmentIntegrationId – Linked integration

• routingPaused, routingPausedRanges – Control routing availability

• inventoryNotTracked, excludeFromTotals – Inventory management flags

Exceptions

Exceptions record operational or system issues requiring attention.

Key Properties:

• exceptionId, exceptionType, exceptionSeverity, exceptionPriority, status

• linkedEntityType, linkedEntityId – Reference to source entity

• Used for error tracking, validation, and escalation workflows

Receipts

Receipts record inbound inventory shipments.

Key Properties:

• receiptId, orderId, arrivalId, expectedQty, receivedQty

• Links to Arrivals and Inventory for reconciliation.

Transfers

Transfers manage stock movements between locations.

Key Properties:

• transferId, sourceLocationId, destinationLocationId, status, lineItems

• Uses xferout, xferfulfill, and xferin events for tracking.

Arrivals

Arrivals record expected incoming shipments for purchase orders.

Key Properties:

• arrivalId, expectedDate, receivedDate, status, linkedPOId

Returns

Returns represent reverse logistics flows for customer or internal returns.

Key Properties:

• returnId, orderId, shipmentId, reason, status, refundAmount

Integrations

Integrations connect Pipe17 to external systems.

Key Properties:

• integrationId, integrationName, connectorId

• status – created, configured, initializing, connected, error, disabled, future

• environment, variables, actions – Configuration and runtime metadata

Connectors

Connectors define supported external system types.

Key Properties:

• connectorId, connectorName, connectorType (eCommerce, 3PL, ERP, WMS, POS, Accounting)

• status, availabilityStatus, selfServiceMode, settings

Data Relationships

Pipe17 maintains a structured hierarchy of relationships:

Schema Mappings

Pipe17’s schema mapping system enables flexible and powerful transformations between systems.

Core Features:

• JavaScript Expression Syntax: Supports data manipulation during transformation.

• Field Path Notation: Dot (field.path) and bracket (array[$0].field) notation supported.

• Default Values and Conditional Logic: $D() and if/else logic for field control.

• Array Mapping: Supports multi-line item and nested structures.

• Validation: Public mappings are automatically validated.

Example:

{
  "name": "Transform Quantity",
  "enabled": true,
  "source": "external.line_items[$0].qty",
  "target": "p17.lineItems[$0].quantity",
  "transform": "$N(source.qty) > 0 ? source.qty : 1"
}

Address Structure

Used across entities such as Orders, Shipments, and Locations.

Standard Fields:
firstName, lastName, company, address1, address2, city, stateOrProvince, zipCodeOrPostalCode, country (ISO-2), email, phone

Common Patterns

Multi-Tenancy

Each entity includes orgKey, integration, userId, and apikeyId for tenant isolation.

External System Tracking

ext[Entity]Id, ext[Entity]ApiId fields map records to external systems.

Metadata Fields

customFields, tags, exceptions, internal — support flexible categorization and internal usage.

Audit Trail

Entities include createdAt, updatedAt, and timeline[] fields.
Automation is tracked through autoEngUpdateStatus.

Shipping Configuration

Pipe17 prioritizes shipping method resolution as follows:

1. shippingCode (highest priority)

2. shippingCarrier + shippingClass

3. Controlled by shippingMethodMapping (boolean flag)

Physical Dimensions

Weight and size fields are supported across Products, Fulfillments, and Shipments:

• weight, weightUnit (lb, oz, kg, g)

• height, length, width, dimensionsUnit (cm, in, ft)

Design Principles

• Canonical Schema: Ensures consistent structure across entities.

• Extensibility: Allows custom fields for business-specific needs.

• Traceability: Maintains linkages to originating systems.

• Status-Driven Workflow: Uses statuses and routing states to drive automation.

• Integration-Centric: Supports bidirectional data exchange.

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.