- Ordering
Understanding orders
Orders are the central concept in OrderCloud, bringing together buyers, sellers, products, payments, and other components to form business transactions.
Order direction
Order direction defines how transactions flow between entities. The same endpoints serve all user types (buyer, Marketplace Owner (MPO), or supplier), with direction providing context.
Buyer to MPO transaction
The simplest transaction flow:
Buyer ➔ MPO
- Buyer perspective: Order is "Outgoing"
- MPO perspective: Order is "Incoming"
Order forwarding transaction
When orders contain products from multiple suppliers (product.DefaultSupplierID), they can be forwarded to suppliers:
Buyer ➔ MPO ➔ Supplier
- Buyer: Views "Outgoing" orders
- MPO: Views both "Incoming" (from buyer) and "Outgoing" (to supplier) orders
- Supplier: Views "Incoming" orders
Buyer to supplier transaction
Direct buyer-to-supplier orders (introduced in API 1.0.214):
Buyer ➔ Supplier
- Buyer: Views "Outgoing" orders
- Supplier: Views "Incoming" orders
- MPO: Uses "All" direction for visibility
Order statuses
Orders progress through various states:
- Unsubmitted: Created but not submitted
- Open: Submitted but not fulfilled
- AwaitingApproval: On hold for approval
- Declined: Submitted but declined
- Completed: All line items shipped
- Canceled: Order cannot be submitted (final state)
The platform automatically tracks status changes and timestamps.
Validation
Order validation occurs through POST v1/orders/{direction}/{orderID}/validate or during submission. Checks include:
- Order calculation status
- User authorization
- Currency matching
- Product availability
- Payment acceptance
- Promotion eligibility
- Price synchronization
- Inventory availability
Additional features
Gratuity
Optional positive decimal value for tips or donations.
Fees
Additional charges set during OrderCalculate. Store fee details in response extended properties.
Shipping and taxes
Costs set during OrderCalculate or by authorized users.
Unsubmitted order cleanup
Automatic cleanup policy:
| User Type | Has Line Items | Retention Period |
|---|---|---|
| All | No | 24 hours |
| Anonymous | Yes | 7-60 days (configurable) |
| Profiled | Yes | 90 days from LastUpdated |
Resource interactions
Common OrderCloud resources that interact with orders:
| Resource | Function |
|---|---|
| Price Schedules | Define ordering rules |
| Buyer Addresses | Manage approved addresses |
| Promotions | Apply order discounts |
| Payments | Process payment methods |
| Approvals | Route orders for approval |
| Shipments | Manage multiple shipments |