When a customer service agent creates or updates a return request or exchange request in the Agent Console, the Return Request Update webhook sends a POST request to the URL you have configured. (Typically this is the URL where your OMS or gateway listens for requests.) The body of the request contains the following data in JSON format:
The complete order data from the original Order Submit POST request.
The new or updated return or exchange request.
For an exchange request, the new order data from the exchange.
The order management system converts the JSON data into the system’s native format, and returns an HTTP status code indicating whether the data was received successfully. A 200-level status code indicates the POST was successful. Any other code indicates failure; if this occurs, Return Request Update sends the POST request again. The webhook is executed up to five times until it succeeds or gives up.
Oracle Commerce Cloud provides versions of the Return Request Update webhook that exclude payment details from the order data you send to systems that do not comply with PCI DSS. See Understand webhooks and PCI DSS compliance for more information.
Return Request Update request example
The following example shows the body of a Return Request Update webhook POST request from Oracle Commerce Cloud. In this example, a customer service agent initiated a return request for the order shown in the Order Submit request example. The original order included two items. One of them is returned in this request.
{"return": {
"replacingItems": false,
"replacementOrder": null,
"otherRefund": 0,
"unAdjustedRefundSubtotal": 60,
"authorizationNumber": "100003",
"state": "PENDING_CUSTOMER_ACTION",
"processName": "Return",
"originatingOrder": {
"lastModifiedTime": 1458154864844,
"shippingGroupCount": 1,
"paymentGroupCount": 1,
"locale": "en",
"state": "NO_PENDING_ACTION",
"shippingGroups": [{
"id": "sg40430",
"specialInstructions": {},
"handlingInstructions": [],
"trackingNumber": null,
"priceInfo": {
"amount": 25,
"currencyCode": "USD",
"shippingTax": 1.56,
"amountIsFinal": false,
"discounted": false,
"rawShipping": 25
},
"shippingGroupClassType": "hardgoodShippingGroup",
"description": "sg40430",
"actualShipDate": null,
"submittedDate": null,
"commerceItemRelationships": [{
"amount": 0,
"id": "r40407",
"commerceItemExternalId": null,
"relationshipType": "SHIPPINGQUANTITY",
"returnedQuantity": 2,
"quantity": 1,
"commerceItemId": "ci3000439"
}],
"state": "INITIAL",
"shipOnDate": null,
"shippingMethod": "standardShippingMethod",
"shippingAddress": {
"middleName": null,
"lastName": "Shopper",
"ownerId": null,
"state": "MA",
"address1": "10 Cloverfield Lane",
"address2": null,
"address3": null,
"companyName": null,
"suffix": null,
"country": "US",
"city": "Boston",
"postalCode": "02134",
"faxNumber": null,
"phoneNumber": "666-123-4567",
"county": null,
"email": "Sally@shopper.com",
"prefix": null,
"firstName": "Sally",
"jobTitle": null
},
"stateDetail": null
}],
"commerceItems": [{
"id": "ci3000439",
"productDisplayName": "BioShock",
"returnedQuantity": 2,
"priceInfo": {
"amount": 90,
"quantityDiscounted": 0,
"discountable": true,
"shippingSurcharge": 0,
"onSale": true,
"priceListId": "salePrices",
"rawTotalPrice": 149.97,
"currencyCode": "USD",
"listPrice": 49.99,
"amountIsFinal": false,
"discounted": false,
"currentPriceDetailsSorted": [{
"amount": 90,
"currencyCode": "USD",
"tax": 5.63,
"range": {
"lowBound": 0,
"highBound": 2,
"size": 3
},
"amountIsFinal": false,
"discounted": false,
"orderDiscountShare": 0,
"quantity": 3,
"detailedUnitPrice": 30
}],
"salePrice": 30
},
"catalogId": null,
"quantity": 1,
"lineAttributes": [],
"catalogRefId": "sku10033",
"catalogKey": null,
"externalId": null,
"productId": "prod10032"
}],
"id": "o30430",
"siteId": "siteUS",
"paymentGroups": [{
"id": "pg30412",
"amount": 122.19,
"currencyCode": "USD",
"billingAddress": {
"middleName": null,
"lastName": "Shopper",
"ownerId": null,
"state": "MA",
"address1": "10 Cloverfield Lane",
"address2": null,
"address3": null,
"companyName": null,
"suffix": null,
"country": "US",
"city": "Boston",
"postalCode": "02134",
"faxNumber": null,
"phoneNumber": "666-123-4567",
"county": null,
"email": "Sally@shopper.com",
"prefix": null,
"firstName": "Sally",
"jobTitle": null
},
"amountAuthorized": 122.19,
"paymentMethod": "tokenizedCreditCard"
}],
"taxPriceInfo": {
"currencyCode": "USD",
"isTaxIncluded": false,
"countryTax": 0,
"stateTax": 7.1899999999999995,
"cityTax": 0,
"districtTax": 0,
"miscTaxInfo": {},
"amount": 7.19,
"valueAddedTax": 0,
"countyTax": 0,
"amountIsFinal": false,
"miscTax": 0,
"discounted": false
},
"priceInfo": {
"amount": 90,
"total": 122.19,
"shipping": 25,
"currencyCode": "USD",
"tax": 7.19,
"amountIsFinal": false,
"discounted": false,
"manualAdjustmentTotal": 0,
"rawSubtotal": 90,
"discountAmount": 0
},
"profileId": "110458",
"creationTime": 1458150828000,
"priceGroupId": "defaultPriceGroup",
"salesChannel": "default",
"relationships": [{
"id": "r40408",
"amount": 122.19,
"relationshipType": "ORDERAMOUNTREMAINING",
"paymentGroupId": "pg30412"
}],
"profile": {
"middleName": null,
"lastName": null,
"email": null,
"firstName": null,
"shippingAddress": null
},
"totalCommerceItemCount": 1
},
"actualShippingRefund": 16.66,
"unallocatedAmount": 0,
"refundMethodList": [{
"amount": 80.41,
"maximumRefundAmount": -1,
"refundType": "manualRefund"
}],
"allocatedAmount": 80.41,
"returnCalculationOrder": null,
"actualTaxRefund": 3.75,
"processImmediately": false,
"authorizationDate": "2016-03-16T19:01:04.852Z",
"relatedReplacementOrders": [],
"refundSubtotal": 80.41,
"returnFee": 0,
"totalRefundAmount": 80.41,
"returnPaymentState": "Refund",
"totalReturnItemRefund": 60,
"totalItemRefund": 60,
"suggestedTaxRefund": 3.75,
"replaceItemCount": 0,
"agentId": "service",
"adjustmentAmount": 20.41,
"suggestedShippingRefund": 16.66,
"processed": false,
"returnItemCount": 2,
"nonReturnItemSubtotalAdjustment": 0,
"submitExchangeAllowed": false,
"originOfReturn": "contactCenter",
"returnItemList": [{
"commerceItem": {
"id": "ci3000439",
"productDisplayName": "BioShock",
"returnedQuantity": 2,
"priceInfo": {
"amount": 90,
"quantityDiscounted": 0,
"discountable": true,
"shippingSurcharge": 0,
"onSale": true,
"priceListId": "salePrices",
"rawTotalPrice": 149.97,
"currencyCode": "USD",
"listPrice": 49.99,
"amountIsFinal": false,
"discounted": false,
"currentPriceDetailsSorted": [{
"amount": 90,
"currencyCode": "USD",
"tax": 5.63,
"range": {
"lowBound": 0,
"highBound": 2,
"size": 3
},
"amountIsFinal": false,
"discounted": false,
"orderDiscountShare": 0,
"quantity": 3,
"detailedUnitPrice": 30
}],
"salePrice": 30
},
"catalogId": null,
"quantity": 1,
"lineAttributes": [],
"catalogRefId": "sku10033",
"catalogKey": null,
"externalId": null,
"productId": "prod10032"
},
"suggestedShippingSurchargeRefundShare": 0,
"unAdjustedRefundAmount": 60,
"state": "AWAITING_RETURN",
"returnShipmentRequired": true,
"stateDetailAsUserResource": "Approved",
"quantityToProcess": 2,
"id": "100003",
"shippingGroupId": "sg40430",
"refundAmount": 60,
"quantityReturned": 2,
"actualTaxRefundShare": 3.75,
"quantityAvailable": 0,
"stateAsUserResource": "Approved",
"orderDiscountAdjustment": 0,
"suggestedShippingRefundShare": 16.66,
"actualShippingRefundShare": 16.66,
"disposition": null,
"quantityToExchange": 0,
"promotionValueAdjustments": {},
"suggestedTaxRefundShare": 3.75,
"itemCostAdjustments": [
{
"taxShareAdjustment": 0,
"shippingShareAdjustment": -16.66,
"amountAdjustment": 0,
"shippingGroupId": "sg40430",
"quantityAdjusted": 0,
"orderDiscountShareAdjustment": 0,
"manualAdjustmentShareAdjustment": 0,
"commerceItemId": "ci3000439"
},
{
"taxShareAdjustment": -3.75,
"shippingShareAdjustment": 0,
"amountAdjustment": -60,
"shippingGroupId": "sg40430",
"quantityAdjusted": 2,
"orderDiscountShareAdjustment": 0,
"manualAdjustmentShareAdjustment": 0,
"commerceItemId": "ci3000439"
}
],
"quantityReceived": 0,
"editable": true,
"actualShippingSurchargeRefundShare": 0,
"quantityShipped": -1,
"manualAdjustmentShare": 0,
"quantityToReturn": 2,
"suggestedRefundAmount": 60,
"comments": null,
"returnReason": "didNotMeetExpectations"
}],
"returningItems": true,
"totalOrderPromotionValueAdjustmentChange": 0,
"comments": null
}}
