---
title: Understanding orders
slug: orders
abstract: Bringing together buyers, sellers, products, payments, and other components to form business transactions.
content_type: concept
audience: \[developer, architect, business-user]
---
# 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](https://api-docs.sitecore.com/ordercloud/orders/orders.forward) 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](https://doc.sitecore.com/ordercloud/en/developers/platform/order-checkout.html#ordercalculate). Store fee details in response extended properties.

### Shipping and taxes

Costs set during [OrderCalculate](https://doc.sitecore.com/ordercloud/en/developers/platform/order-checkout.html#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](https://doc.sitecore.com/ordercloud/en/developers/platform/order-checkout.html#ordercalculate).

#### 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](https://doc.sitecore.com/ordercloud/en/developers/platform/order-checkout.html#ordercalculate) during checkout.

---

## Related reading

- [Security profiles and roles](https://doc.sitecore.com/ordercloud/en/developers/platform/security-profiles-and-roles.html)
- [Understanding OrderCloud assignments](https://doc.sitecore.com/ordercloud/en/developers/platform/assignments.html)
- [Order synchronization](https://doc.sitecore.com/ordercloud/en/developers/platform/ordersync.html)
- [Group ordering](https://doc.sitecore.com/ordercloud/en/developers/platform/group-ordering.html)