---
title: Order returns
slug: order-returns
abstract: OrderCloud provides comprehensive features for managing the complete order return process.
content_type: concept
audience: \[architect, business-user, developer]
---
# Order returns

OrderCloud provides comprehensive features for managing the complete order return process. This functionality enables businesses to handle returns, refunds, and related workflows while maintaining flexibility for different business requirements.

## Key features

### Return structure

- Each `OrderReturn` links to an existing `Order`
- `ItemsToReturn` connects to existing `LineItems`
- No minimum requirements for items or quantities
- Supports physical and non-physical returns

### Flexible refund options

- Process returns without physical items
- Handle partial refunds for:
  - Expedited shipping charges
  - Processing delays
  - Damaged items
  - Service adjustments

### Access control

- `Shopper` role users:
  - Create returns for their orders (`Order.FromUserID`)
  - Limited to their own transactions
  - Cannot process anonymous returns

- `OrderAdmin` role users:
  - Create returns for visible orders based on scope:
    - Marketplace Owners: All marketplace orders
    - Suppliers: Orders placed to them (`Order.ToCompanyID`)
    - Buyer users: Company orders (`Order.FromCompanyID`)

### Order requirements

- Status must be `Open` or `Completed`
- For `Open` orders:
  - Only shipped items eligible
  - Quantity restrictions based on shipment status

### Policy management

- Implement date-based return policies through:
  - User interface controls
  - `SellerApprovalRules` configuration
  - Custom validation rules

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/e7cfe66376174bb8bb1a2e310a04aac4.png)

## OrderReturn resource

Core model for managing returns:

```json
{
  "ID": "",
  "OrderID": "",
  "PaymentIDs": [],
  "Status": "",
  "RefundAmount": 0,
  "ItemsToReturn": [],
  "DateCreated": "2022-01-04T00:00:00.00+00:00",
  "DateSubmitted": "2022-01-04T00:00:00.00+00:00",
  "DateApproved": "2022-01-04T00:00:00.00+00:00",
  "DateDeclined": "2022-01-04T00:00:00.00+00:00",
  "DateCanceled": "2022-01-04T00:00:00.00+00:00",
  "DateCompleted": "2022-01-04T00:00:00.00+00:00",
  "LastUpdated": "2022-01-04T00:00:00.00+00:00",
  "xp": {}
}
```

Item return details:

```json
"ItemToReturn": {
  "LineItemID": "",
  "Quantity": 0,
  "RefundAmount": 0,
  "Comments": ""
}
```

### API endpoints

Return management:

- `GET v1/orderreturns` (supports `approvable` filter for pending approvals)
- `GET v1/orderreturns/{returnID}`
- `POST v1/orderreturns`
- `PUT v1/orderreturns/{returnid}`
- `PATCH v1/orderreturns/{returnid}`
- `DELETE v1/orderreturns/{returnid}`

Item management:

- `DELETE v1/orderreturns/{returnid}/items/{lineitemid}`
- Create/update items via OrderReturn endpoints

Status management:

- `POST v1/orderreturns/{returnid}/submit`
- `POST v1/orderreturns/{returnid}/approve`
- `POST v1/orderreturns/{returnid}/decline`
- `POST v1/orderreturns/{returnid}/cancel`
- `POST v1/orderreturns/{returnid}/complete`

Approval management:

- `GET v1/orderreturns/{returnID}/approvals`
- `GET v1/orderreturns/{returnID}/eliglbleapprovers`

### Important notes

Required fields:

- `OrderID` on OrderReturn
- `LineItemID` on ItemsToReturn

Refund handling:

- `OrderReturn.RefundAmount`: Automatically calculated as sum of ItemsToReturn RefundAmounts
- `OrderAdmin` users can set RefundAmount directly when no items are returned
- Supports partial and full refunds

## SellerApprovalRule resource

Configuration model for return approval rules:

```json
{
  "ID": "",
  "Name": "",
  "Type": "OrderReturn",
  "Description": "",
  "OwnerID": "",
  "ApprovingGroupID": "",
  "RuleExpression": ""
}
```

### API endpoints

Rule management:

- `GET v1/approvalrules`
- `GET v1/approvalrules/{ruleID}`
- `POST v1/approvalrules`
- `PUT v1/approvalrules/{ruleID}`
- `PATCH v1/approvalrules/{ruleID}`
- `DELETE v1/approvalrules/{ruleID}`

### Important notes

Access control:

- Not available to buyer users
- `OwnerID` identifies rule owner organization
- Only Marketplace Owner can set other organization IDs
- Used for ApprovingGroupID lookup and admin eligibility

Date-based rules:

- Uses `now()` function for time-based policies
- Example: 30-day return window

  ```
  Order.DateCompleted < now(-30)
  ```

- Can combine with UI validation

Current support:

- `OrderReturn` type only
- Future expansion planned for Order Approvals

## OrderReturn integration event

OrderCloud provides integration flexibility for refund calculations, recognizing that businesses may have complex requirements involving:

- Tax adjustments
- External system synchronization
- Custom calculation rules
- Business-specific policies

### OrderCloud payload

```json
{
  "OrderReturn": {},
  "OrderWorksheet": {}
}
```

### Expected response

```json
{
  "RefundAmount": 0,
  "ItemsToReturnCalcs": [
    {
      "LineItemID": "",
      "RefundAmount": ""
    }
  ],
  "xp": {}
}
```

### Integration notes

Implementation:

- Endpoint: `/calculateorderreturn` at `CustomImplementationUrl`
- Internal OrderCloud call on return creation/update
- Middleware updates must wait for response completion

Execution rules:

- Skipped if `OrderAdmin` provides valid refund amounts
- Sets null refunds if no integration event for `Shopper` role
- Supports custom calculation logic

## Message sender types

Notification events:

- `OrderReturnSubmitted`
- `OrderReturnApproved`
- `OrderReturnDeclined`
- `OrderReturnCompleted`
- `OrderReturnSubmittedForApproval`
- `OrderReturnSubmittedForYourApproval`
- `OrderReturnSubmittedForYourApprovalHasBeenApproved`
- `OrderReturnSubmittedForYourApprovalHasBeenDeclined`

Note: For marketplace owner assignment, leave both `BuyerID` and `SupplierID` null

## Additional properties

### Payment.OrderReturnID

- Links payments to OrderReturn.PaymentIDs
- Enforces refund limits:
  - Cannot exceed Order.Total
  - Cannot exceed OrderReturn refund amount
- Requires negative Payment.Amount for refunds
- Automatically completes OrderReturn when refund amounts match

### Product.Returnable

- Controls product return eligibility
- Restricts non-OrderAdmin users based on setting
- Supports product-level return policies

### ApiClient.OrderReturnIntegrationEventID

- Enables integration event for return processing
- Triggers on return creation and updates
- Supports custom calculation logic

## System maintenance

Cleanup process:

- Targets unsubmitted returns
- Deletes after 14 days without updates
- Maintains system efficiency

## Order returns - Handling calculations

OrderCloud provides flexibility in calculating refund amounts for product returns. This guide explains key considerations and implementation approaches.

### Integration event

The [OrderReturn Integration Event](https://doc.sitecore.com/ordercloud/en/developers/platform/order-returns.html#orderreturn-integration-event) triggers when an `OrderReturn` is created or updated without a specified `RefundAmount`. The event includes the order worksheet.

### Order worksheet importance

The `OrderWorksheet` provides essential data for refund calculations. Store tax, shipping, and promotion data during order calculation for accurate refund processing.

#### Storing calculation data

Store calculation values in `OrderWorksheet.OrderCalculateResponse.xp` during checkout (`POST v1/orders/{direction}/{orderID}/calculate`). Example calculation object:

```json
{
  "OrderTotals": {
    "Subtotal": 170,
    "LineItemPromotionTotal": 10,
    "OrderPromotionTotal": 20,
    "OrderTaxableSubtotal": 140,
    "LineItemTax": 11.29,
    "ShippingSubtotal": 25,
    "ShippingTax": 3.25,
    "TotalCharged": 179.54
  },
  "LineItems": [
    {
      "ID": "X001",
      "Quantity": 2,
      "UnitPrice": 5,
      "Subtotal": 10,
      "LineTaxableSubtotal": 10,
      "Tax": 0,
      "Total": 10,
      "OrderPromotionEligible": false,
      "LineItemPromoAppliedToTaxableSubtotal": 0,
      "OrderLevelPromoNotAppliedToTaxableSubtotal": 0
    },
    {
      "ID": "X002",
      "UnitPrice": 60,
      "Quantity": 1,
      "Subtotal": 60,
      "LineTaxableSubtotal": 50,
      "Tax": 3.76,
      "Total": 53.76,
      "OrderPromotionEligible": true,
      "LineItemPromoAppliedToTaxableSubtotal": 10,
      "OrderLevelPromoNotAppliedToTaxableSubtotal": 6.67
    },
    {
      "ID": "X003",
      "UnitPrice": 50,
      "Quantity": 2,
      "Subtotal": 100,
      "LineTaxableSubtotal": 100,
      "Tax": 7.53,
      "Total": 107.53,
      "OrderPromotionEligible": true,
      "LineItemPromoAppliedToTaxableSubtotal": 0,
      "OrderLevelPromoNotAppliedToTaxableSubtotal": 13.33
    }
  ],
  "Shipping": [
    {
      "RateID": "bf379e3bee624fb281ebaedeb3ad4893",
      "LineItemIDs": ["X001", "X002"],
      "Subtotal": 10,
      "Tax": 1.3,
      "Total": 11.3
    },
    {
      "RateID": "82c8fbf908d142a3919a2f958eb25de3",
      "LineItemIDs": ["X003"],
      "Subtotal": 15,
      "Tax": 1.95,
      "Total": 16.95
    }
  ]
}
```

### Calculation considerations

#### Order totals

- Track line items, shipping, promotions, and tax effects
- Handle tax-exempt items
- Apply line item and order-level promotions
- Calculate taxable subtotals

#### Taxes and promotions

- Handle order-level promotion distribution
- Apply line item promotions before tax calculation
- Consider tax service capabilities for promotion handling

#### Shipping

- Track multiple shipment costs
- Calculate shipping tax per shipment
- Handle partial shipping refunds

### Return calculation types

Use `OrderReturn.xp.ReturnType` to route returns to appropriate calculation methods.

#### Standard return invoicing

Recommended approach using tax services:

- Creates return invoices
- Handles complex tax calculations
- Manages partial returns
- Ensures accurate tax distribution

Example return response:

```json
{
  "OrderReturnResponse": {
    "RefundAmount": 104.20,
    "ItemsToReturnCalcs": [
      {
        "LineItemID": "X001",
        "RefundAmount": 10
      },
      {
        "LineItemID": "X002",
        "RefundAmount": 47.09
      },
      {
        "LineItemID": "X003",
        "RefundAmount": 47.11
      }
    ]
  }
}
```

#### Custom returns

Handle special cases with extended properties:

```json
{
  "xp": {
    "ReturnType": "Shipping",
    "AmountType": "Fixed",
    "RefundAmount": 11.30
  }
}
```

Return types:

- Shipping refunds
- Tax adjustments
- Discretionary refunds

Amount types:

- Fixed amounts
- Percentage-based refunds

## Using order returns for product returns, refunds, and credits

OrderCloud's order returns feature enables digital return experiences for both customers and administrators. This guide demonstrates various return and refund scenarios using OrderReturns.

### Example order

Consider this sample order:

- LineItem 1: 1 qty - Athletic Shoes, size 8.5
- LineItem 2: 4 qty - Socks
- LineItem 3: 1 qty - Customized sports jersey (Customer's name printed)
- LineItem 4: 2 qty - Joggers, size 10

Order breakdown:

| Line | Product | Qty | Price | Total | Tax |
| ------ | --------- | ----- | -------- | -------- | ----- |
| 1 | Athletic Shoes, Size 8.5 | 1 | $75 | $75 | $5.54 |
| 2 | Socks | 4 | $10 | $40 | $3.01 |
| 3 | Customized Sports Jersey | 1 | $100 | $100 | $7.53 |
| 4 | Joggers, Size 10 | 2 | $50 | $100 | $7.53 |
| | Shipping | | $10 | $10 | $0.68 |
| | | | Subtotal | $315.00 | |
| | | | Shipping | $10.00 | |
| | | | Tax | $24.29 | |
| | | | Total | $349.29 | |

### Return scenarios

#### Standard item return

Customer received items 1, 2, and 3, and requests returns for:

- Shoes (too small)
- One pair of socks (excess quantity)

Notes:

- Item 4 unavailable for return (not shipped)
- Item 3 unavailable for return (`Product.Returnable = False`)

Return calculation:

| Line | Product | Qty Ordered | Qty Delivered | Return Qty | Price | Refund (Product + Tax) |
| ------ | --------- | ------------- | --------------- | ------------ | ------- | ---------------------- |
| 1 | Athletic Shoes | 1 | 1 | 1 | $75 | $80.54 |
| 2 | Socks | 4 | 4 | 1 | $10 | $10.75 |
| 3 | Jersey | 1 | 1 | N/A | $100 | - |
| 4 | Joggers | 2 | 0 | N/A | $50 | - |
| | Shipping | | | - | $10 | - |
| | | | | Subtotal | | $85.00 |
| | | | | Tax | | $6.29 |
| | | | | Total | | $91.29 |

Example return request:

```json
{
  "ID": "order3-return4",
  "OrderID": "order3",
  "RefundAmount": 91.29,
  "ItemsToReturn": [
    {
      "LineItemID": "lineitem1",
      "Quantity": 1,
      "RefundAmount": 80.54,
      "Comments": "Shoes are too small"
    },
    {
      "LineItemID": "lineitem2",
      "Quantity": 1,
      "RefundAmount": 10.75,
      "Comments": "Bought too many"
    }
  ]
}
```

#### Shipping refund

For late deliveries, process shipping refunds:

| Line | Product | Qty Ordered | Qty Delivered | Return Qty | Price | Refund |
| ------ | --------- | ------------- | --------------- | ------------ | ------- | --------- |
| 4 | Joggers | 2 | 2 | Late delivery | $50 | - |
| | Shipping | | | Full refund | $10 | $10.68 |
| | | | | Subtotal | | $10.00 |
| | | | | Tax | | $0.68 |
| | | | | Total | | $10.68 |

Example shipping refund request:

```json
{
  "ID": "order3-return2",
  "OrderID": "order3",
  "RefundAmount": 10.68,
  "ItemsToReturn": [
    {
      "LineItemID": "lineitem4",
      "Quantity": 2,
      "Comments": "Item arrived late"
    }
  ]
}
```

#### Price match refund

For price matching within 2 weeks of purchase:

| Line | Product | Qty | Price | Competitor Price | Refund |
| ------ | --------- | ----- | ------- | ------------------ | --------- |
| 4 | Joggers | 2 | $50 | $45.99 | $8.02 (2 @ $4.01) |

#### Customer service refund

For general customer satisfaction:

```json
{
  "ID": "order3-return3",
  "OrderID": "order3",
  "RefundAmount": 5,
  "Comments": "50% shipping discount due to unsatisfied customer.",
  "ItemsToReturn": []
}
```

### Implementation flexibility

OrderCloud provides flexibility in:

- Return policies
- Refund calculations
- Process workflows
- Resource customization

---

## Related reading

- [Cart](https://doc.sitecore.com/ordercloud/en/developers/platform/cart.html)
- [Premium search](https://doc.sitecore.com/ordercloud/en/developers/platform/premium-search.html)
- [Calculating promotion discounts](https://doc.sitecore.com/ordercloud/en/developers/platform/custom-promotion-discounts.html)