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

OrderReturn resource

Core model for managing returns:

{
  "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:

"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:

{
  "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

{
  "OrderReturn": {},
  "OrderWorksheet": {}
}

Expected response

{
  "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

Related reading

• Order returns - handling calculations
• Introducing the Cart API
• Introducing premium search