1. Ordering

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:

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

LineProductQtyPriceTotalTax
1Athletic Shoes, Size 8.51$75$75$5.54
2Socks4$10$40$3.01
3Customized Sports Jersey1$100$100$7.53
4Joggers, Size 102$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:

LineProductQty OrderedQty DeliveredReturn QtyPriceRefund (Product + Tax)
1Athletic Shoes111$75$80.54
2Socks441$10$10.75
3Jersey11N/A$100-
4Joggers20N/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:

LineProductQty OrderedQty DeliveredReturn QtyPriceRefund
4Joggers22Late delivery$50-
ShippingFull 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:

LineProductQtyPriceCompetitor PriceRefund
4Joggers2$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
If you have suggestions for improving this article, let us know!