Ordering

Ordering
Understanding orders

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

Order fees

Overview

Order fees help businesses manage operational costs and maintain profitability. They provide transparency for expenses that aren't easily included in product pricing, helping manage customer expectations while ensuring sustainable operations.

Fee types

Common order fee examples include:

Minimum order fees: Applied when orders don't meet minimum value requirements
Environmental fees: Cover eco-friendly packaging, carbon offsets, or recycling programs
Facility fees: Support venue maintenance, security, cleaning, and utilities
Tariff fees: Display import costs separately for pricing transparency

Adding and displaying fees

Order calculation

The Order Calculate event response includes a FeeTotal property for order totals. Learn more about order calculation.

Shopping experience

Store fee information in PriceSchedule extended properties (xp) for display during shopping. Access this data through:

GET v1/me/products
GET v1/me/products/{productID}

Example fee configuration:

json

{
  "xp": {
    "AdditionalFees": [
      {
        "Name": "Facility Fee",
        "PerQuantity": false,
        "Amount": 3.0
      },
      {
        "Name": "Tariff",
        "PerQuantity": true,
        "Amount": 5.0
      }
    ]
  }
}

Checkout display

Use fee values from the order worksheet calculate response during checkout.

If you have suggestions for improving this article, let us know!