Order Objects: Fields and Relationships

Identification Fields

• orderId - Auto-generated, read-only unique identifier in the app.

• extOrderId - External order ID from the source system.

• extOrderApiId - External API identifier. Uniqueness constraint per organization when present; elevate visibility in integrations that generate both IDs.

• extOrderUrl - Deep link to the order in the external system.

Status Fields

Order Status (Lifecycle)

draft → new → onHold → toBeValidated → reviewRequired → readyForFulfillment → sentToFulfillment → partialFulfillment → fulfilled → inTransit → partialReceived → received → canceled → returned → refunded → archived → closed
This extends the basic list shown previously.

Routing Status

disabled, pending, ready, acknowledged, failed, excluded, pendingInventory
Clarification: routingStatus automatically changes to ready when status becomes readyForFulfillment.

Parallel Workflow Statuses

• paymentStatus – Order-level payment state.

• fulfillmentStatus – Order-level fulfillment state.

Disposition

Order-level disposition is an array of OrderDispositionType values (separate from line-item dispositions):

• partiallyRouted, routed

• partiallySent, sent

• partiallyFulfilled, fulfilled

• partiallyCanceled, canceled

• partiallyFailed, failed

• partiallyRejected, rejected

• partiallyUnrouted, unrouted

• partiallyUnsent, unsent

• partiallyUnfulfilled, unfulfilled
  This corrects earlier examples that implied a single value.

Timestamps

• createdAt, updatedAt – System timestamps.

• extOrderCreatedAt, extOrderUpdatedAt – Source timestamps.

• lastRoutedAt – When the Order Routing Engine last routed the order.

• holdUntil – Do not process before this date/time.

• fulfilledAt – Set when the order reaches fulfilled (added).

Customer Information

• customer object

  • customerId (internal), extCustomerId, extCompanyCustomerId, extLocationCustomerId

  • type: individual | company

  • firstName, lastName, company, email, phone

  • billingAddress, shippingAddress (see Address structure)

Address Structure

Used by customer addresses, shipping destinations, and locations.

• firstName, lastName, company

• address1, address2, city, stateOrProvince, zipCodeOrPostalCode, country (ISO-2)

• email, phone

• addressType: residential | commercial | institutional | military | pobox | other

Order Details

• currency

• orderSource (originating app)

• orderSourceType: online, pos, wholesale, edi, other, b2b (explicit list)

• subTotalPrice, orderTax, orderDiscount, shippingPrice, totalPrice

• customerPONumber – Promoted to this section for procurement workflows.

• giftNote, orderNote, shippingNote

• incoterms – International Commercial Terms.

• privacyPolicy – Array of privacy policies to apply (for example, ["amazon"]).

• paymentTerms – Object defining terms (for example, net days, due date).

• replacementOrderId, replacementReason – See “Order replacement.”

Line Items

Array of items on the order.

• sku, uniqueId, name

• quantity – Current editable quantity

• ordered – Original quantity as reported by source

• fulfillable – Quantity the source marks as fulfillable

• fulfilled, canceled, returned, refunded – Result quantities

• reported – Reported quantity (source reconciliation)

• itemPrice, itemDiscount, itemTax

• requiresShipping, requiresShippingSource

• quantityUnit (for example, each, can, bottle)

• locationId – Preferred origin

• preferredLocationGroupId – Array of preferred location-group IDs

• trackedAtSourceChannel – Boolean

• upc – Item UPC

• shippingOptions – Array of packaging/handling flags: SIOC, polyBagging, bubbleWrapping, taping, singleLocationShipping, allOrNoneShipping

Line-item dispositions

Dispositions are tracked as quantities by type:

dispositions: [
  {
    uniqueId: "line-item-id",
    values: [
      { type: "routed",     quantity: 5 },
      { type: "fulfilled",  quantity: 3 },
      { type: "unrouted",   quantity: 2 }
    ]
  }

Types: routed, sent, failed, rejected, fulfilled, canceled, unrouted, unsent, unfulfilled

Shipping Information

• shippingCarrier + shippingClass – Required together for service selection.

• shippingCode – Highest priority mapping; overrides carrier/class.

• requireShippingLabels – If label purchase is required.

• expectedDeliveryDate, shipAfterDate, shipByDate, shipCancelByDate – Critical dates.

• shippingDestinations – For multi-destination orders (moved here from Misc).

Financial Information

Payments

• payments[].method: cash, giftCard, creditCard, storeCredit, paypal, other, custom

• payments[].customMethod – Name when method = custom

• payments[].kind – Card network where applicable: visa, mastercard, amex, discover

• amount, currency, status (succeeded | failed), processedAt, reference

Discounts

• discounts[].type (coupon, manual, other), value, label, reference

• discounts[].lineItemId, discounts[].createdAt – Line-level targeting and audit

Additional Charges

• additionalCharges[].type (handling, wrapping, shipping, other), value, label, reference

• additionalCharges[].lineItemId, additionalCharges[].createdAt

Refunds

• refunds[].type, value, processedAt, reference

• refunds[].lineItemId, lineItemQuantity, lineItemRestock, label

Automation and Routing

• autoEngUpdateStatus, autoEngUpdateStatusUpdatedAt – Automation governance.

• lastRerunRoutingTrigger: manual | auto – Trigger provenance.

• preferredLocationGroupId (order level) – Steering to eligible groups

• fulfilledAt – Set when the order is fully fulfilled

Privacy and Compliance

• privacyPolicy – Array designating policy sets to enforce (for example, marketplace-specific privacy constraints such as Amazon).

Order Replacement

• replacementOrderId – Reference to the order being replaced

• replacementReason – damaged, lostInTransit, wrongItem, other

Multi-Destination Orders

• isMultiDestination – Preferred current name

• isMultiAddress – Legacy alias retained for compatibility

• shippingDestinations[] – Destination-level address, items, and constraints
  Ensure routing rules consider destination-level inventory and carrier availability.

Audit and History

• timeline[] – Changelog entries: who, when, what changed, previous vs new values

• lineItemsEdits[] – History of item-level edits and their reasons

• exceptionCategories[], hasException (GraphQL) – Exception rollups

• internal – System-reserved annotations; not exposed publicly.

Key Relationships

• Organization – Every order belongs to an org via orgKey.

• Integration – Set automatically to the integration ID bound to the API key used to create the order (clarification).

• Products – Each line item’s sku links to a catalog product.

• Locations – locationId indicates default origin and constrains routing.

• Shipments (formerly “Shipping Requests”) – Created by the routing process; linked by orderId. Terminology corrected across the doc.

• Fulfillments – Completion artifacts associated to shipments.

• Exceptions – Array contains type strings (for example, eOutOfStock, eInvalidAddress); exceptionCategories holds category IDs (clarification).

Field Requirements

Validation rules

• Max 10 orders per batch create request

• extOrderId + orderSource must be unique per organization

• If provided, extOrderApiId must be unique per organization

• lineItems.uniqueId values must be unique within an order

Common Use Cases

• Standard order creation – Single destination, standard routing

• Multi-destination – Use shippingDestinations and destination-level items

• Replacement order – Reference original via replacementOrderId and set replacementReason

• Hold and release – Set holdUntil, Automation moves to readyForFulfillment when expired

• Pre-order / future inventory – Combine pendingInventory routing status with future inventory features

Order Lifecycle Flow (Reference)

1. Order is created (often new).

2. Automation can place the order onHold until holdUntil.

3. When ready, status becomes readyForFulfillment → routingStatus changes to ready.

4. Order Routing Engine creates shipments and sets sentToFulfillment.

5. Logistics connectors sync shipments to providers.

6. Providers create fulfillments in the app.

7. As fulfillments post, the order may become partialFulfillment or fulfilled; record fulfilledAt when fully fulfilled.

Order Routing Process (Reference)

Routing evaluates orders with routingStatus = ready, applies rules, creates shipments, and sets routingStatus = acknowledged on success. Factors include inventory, proximity, custom rules, and future inventory.

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.