1. Ordering

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