Updated by Miranda Posthumus
We’re excited to present a new set of features to enable all aspects of the Order Returns process. These features will be available in all regions and environments by the end of May 2022.
OrderReturn
must be affiliated with an existing Order
, and ItemsToReturn
must be affiliated with existing LineItems
OrderReturn
is not required to have any ItemsToReturn
, and ItemsToReturn
are not required to have a Quantity
specified Shopper
role can create an OrderReturn
for any order from them (Order.FromUserID
)OrderReturns
OrderAdmin
role can create an OrderReturn
for any Order
visible to themOrder.ToCompanyID
)Order.FromCompanyID
)Order.Status
must be Open
or Completed
to create an associated OrderReturn
Order.Status
is Open
, only the quantity of a given item that has already shipped will be eligible to returnSellerApprovalRules
resourceOrderReturn
"OrderReturn": {
"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": {}
}
"ItemToReturn": {
"LineItemID": "",
"Quantity": 0,
"RefundAmount": 0,
"Comments": ""
}
Endpoints:
GET v1/orderreturns
approvable
filter to list OrderReturns
awaiting the user's approval GET v1/orderreturns/{returnID}
POST v1/orderreturns
PUT v1/orderreturns/{returnid}
PATCH v1/orderreturns/{returnid}
DELETE v1/orderreturns/{returnid}
DELETE v1/orderreturns/{returnid}/items/{lineitemid}
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
GET v1/orderreturns/{returnID}/approvals
GET v1/orderreturns/{returnID}/eliglbleapprovers
Notes
OrderID
is required, as is LineItemID
on ItemsToReturn
OrderReturn.RefundAmount
is the sum of all RefundAmounts
on ItemsToReturn
. If there are no ItemsToReturn
, Order.RefundAmount
is writable by users with the OrderAdmin
roleSellerApprovalRule
"SellerApprovalRule": {
"ID": "",
"Name": "",
"Type": "OrderReturn",
"Description": "",
"OwnerID": "",
"ApprovingGroupID": "",
"RuleExpression": "",
}
Endpoints:
GET v1/approvalrules
GET v1/approvalrules/{ruleID}
POST v1/approvalrules
PUt v1/approvalrules/{ruleID}
PATCH v1/approvalrules/{ruleID}
DELETE v1/approvalrules/{ruleID}
Notes:
OwnerID
is the ID of the organization who owns the rule. Only the Marketplace Owner can write a value other than their own organization ID. The value is used to look up the ApprovingGroupID
and determine who is eligible to administer the ruleRuleExpressions
the rules engine now supports a new custom function now()
which accepts an integer as a parameterOrderReturn
associated with an Order
that was completed prior to 30 days ago to route for approval, you would set up an SellerApprovalRule
with a RuleExpression
of Order.DateCompleted < now(-30)
OrderReturn
from being initiated on Orders completed more than a specific time agoOrderReturn
is the only supported Type currently - we plan to expand this functionality to Order Approvals in the futureIntegrationEvent
Type: OrderReturn
OrderCloud does not provide an opinion on RefundAmount
at the OrderReturn
or ItemToReturn
levels due to the fact there are an infinite number of ways a seller might wish to calculate a refund, which would likely include complicated external events such as adjusting tax collection records. Since we are unable to provide an informed opinion, we provide sellers with the opportunity to set up a custom IntegrationEvent
to handle OrderReturn
calculations.
Payload provided by OrderCloud to the CustomImplementationUrl
"OrderReturnPayload": {
"OrderReturn": {},
"OrderWorksheet": {}
}
Response expected by OrderCloud
"OrderReturnResponse": {
"RefundAmount": 0,
"ItemsToReturnCalcs": []
}
"LineItemReturnCalculation": {
"LineItemID": "",
"RefundAmount": ""
}
Notes:
POST
the payload to is /calculateorderreturn
at the CustomImplementationUrl
IntegrationEvent
types, there are no publicly available endpoints associated with the event. It is called from within the OrderCloud code when an OrderReturn
is created or updatedOrderAdmin
passes in a valid RefundAmount
(either one for every ItemToReturn
or if there are no ItemsToReturn
a value at the OrderReturn
level), the IntegrationEvent will not be calledOrderReturnSubmitted
OrderReturnApproved
OrderReturnDeclined
OrderReturnCompleted
OrderReturnSubmittedForApproval
OrderReturnSubmittedForYourApproval
OrderReturnSubmittedForYourApprovalHasBeenApproved
OrderReturnSubmittedForYourApprovalHasBeenDeclined
Notes:
MessageSender
to the Marketplace Owner, leave both BuyerID
and SupplierID
null when creating the MessageSender
assignmentPayment.OrderReturnID
Product.Returnable
ApiClient.OrderReturnIntegrationEventID
OrderReturn
CleanupOrderReturns
that have not been updated in the past 14 days will be deleted