Return adjustments are used to categorize different return-level charges. By storing all adjustments as types of adjustments that can be applied to the return, instead of including them in the return header, they can be extended based on the needs of custom implementations and integrations.
RET_ADD_FEATURE_ADJ
Return Additional Feature
RET_DEPOSIT_ADJ
Return Deposit Adjustment
RET_DISCOUNT_ADJ
Return Discount
RET_DUTY_ADJ
RMA Duty
RET_EXT_PRM_ADJ
Return External Promotion Adjustment
RET_FEE_ADJ
Return Fee
RET_MAN_ADJ
Return Manual Adjustment
RET_MISC_ADJ
Return Miscellaneous Charges
RET_MKTG_PKG_ADJ
Return Marketing Package Adjustment
RET_PROMOTION_ADJ
Return Promotion
RET_REPLACE_ADJ
Return Replacement
RET_RMA_ADJ
RMA Fee Adjustment
RET_SALES_TAX_ADJ
Return Sales Tax
RET_SHIPPING_ADJ
Return S&H
RET_SURCHARGE_ADJ
Return Surcharge
RET_VAT_PC_ADJ
Return VAT Price Correction
RET_VAT_TAX_ADJ
Return VAT Tax
RET_WARRANTY_ADJ
Return Warranty
ECOM_RTN_CHANNEL
RETURN_CHANNEL
Ecom Return Channel
01
POS_RTN_CHANNEL
RETURN_CHANNEL
POS Return Channel
02
To create a return for a customer's order that has already been fulfilled and completed, you will need to call the /createReturn endpoint with the POST method.
POST: https://{host}/api/createReturn
Content-Type: application/json
In the request body, include the information necessary for creating a return, including all the parameters listed below:
Parameter Name
Description
externalId
Order identification in the external system (e.g. Shopify or Netsuite)
customerId
Customer’s Identification in HotWax Commerce (partyId)
companyId
Identification for the Company owning the brand
currencyCode
Currency unit of measurement (USD, INR, YEN, etc.)
facilityId
Facility where order is returned
idType
Identification Type
orderId
Unique HotWax Commerce Order Identification
items
List of Order Items
orderName
Shopify Order Name
orderItemSeqId
Order Item Sequence
status
Current status of the return
grandTotal
Sum total of return items
returnIdentificationTypeId
Global Identification for the return (“SHOPIFY_RTN_ID”)
IdValue (in returnIdentification)
Unique Value for return identification
idType
Global Identification Type (SKU, INVOICE_EXPORT, ISBN, UPCA, UPCE)
idValue
Unique Id value for the global identification
shipFrom
Customer's address
shipTo
Destination address for returned order
sku
SKU for returned item
id (in item list)
Product id for that item
price
Price of the individual item
quantity
Product Quantity
orderItemExternalId (in item list)
Order Item id for external system (Shopify or Netsuite)
itemAdjustments
Record of adjustments (taxes or discounts) applied on the particular item
type
Type of return adjustments
returnAdjustments
Record of adjustments applied on the return
Types of Return Adjustments:
Return adjustments are used to categorize different return-level charges. By storing all adjustments as types of adjustments that can be applied to the return, instead of including them in the return header, they can be extended based on the needs of custom implementations and integrations.
RET_ADD_FEATURE_ADJ
Return Additional Feature
RET_DEPOSIT_ADJ
Return Deposit Adjustment
RET_DISCOUNT_ADJ
Return Discount
RET_DUTY_ADJ
RMA Duty
RET_EXT_PRM_ADJ
Return External Promotion Adjustment
RET_FEE_ADJ
Return Fee
RET_MAN_ADJ
Return Manual Adjustment
RET_MISC_ADJ
Return Miscellaneous Charges
RET_MKTG_PKG_ADJ
Return Marketing Package Adjustment
RET_PROMOTION_ADJ
Return Promotion
RET_REPLACE_ADJ
Return Replacement
RET_RMA_ADJ
RMA Fee Adjustment
RET_SALES_TAX_ADJ
Return Sales Tax
RET_SHIPPING_ADJ
Return S&H
RET_SURCHARGE_ADJ
Return Surcharge
RET_VAT_PC_ADJ
Return VAT Price Correction
RET_VAT_TAX_ADJ
Return VAT Tax
RET_WARRANTY_ADJ
Return Warranty
Content-Type: application/json
The response will include all the parameters provided in the request body, along with any error messages and login information.
Discover how returns are generated Return Header wise, with each return containing the list of returned items.
The feed will be generated Return Header wise, with each return containing the list of items returned.
Parameters which can be variable for the Returns Financial Feed Feed are
orderId - Parameter to fetch Return details for a specific orderId.
returnId - Parameter to fetch Return details for a specific returnId.
systemMessageTypeId - The System Message Type ID for generating Returns Financial Feed.
systemMessageRemoteId - The System Message Remote ID to send Returns Financial Feed.
sinceReturnDate - Parameter to fetch Returns after a specific Return Date. This date corresponds to the ReturnHeader.returnDate in HC.
sinceReturnCompletedDate - Parameter to fetch Returns which are completed in HC after a specific Date. This date corresponds to the ReturnStatus.completedDatetime for Return Items in HC.
sinceEntryDate - Parameter to fetch Returns created after a specific Date in HC. This date corresponds to the ReturnHeader.entryDate in HC.
productStoreIds - to set the product store ids to generate brand specific feeds. eg. WSC_STORE
returnChannelEnumId - Identify the Returns being made from different channels like Ecom Returns, In-Store etc.
customParamatersMap - This map defines custom conditions, allowing flexibility in defining new conditions. Eg. {"returnReasonId_op": "empty", "returnReasonId_not": "Y"}
Views used
FinancialReturnItemsSyncQueue
ReturnItemView
In the first entity, find on the FinancialReturnItemsSyncQueue view fetches the eligible records for the feed.
The conditions on the FinancialReturnItemsSyncQueue are:
productStoreId - Support for productStoreId was added to generate brand specific feeds.
If productStoreId comes from the in-parameter productStoreIds which is a list then the productStoreId field is prepared based on the following cases:
If only one value comes in the productStoreIds list then the productStoreId field will be set from that value in the list.
If nothing is passed in the productStoreIds list or there are more than one value in the list then the productStoreId field will be a default prefix that will be set from the property added in the Moqui conf file. In this case, the default prefix will be 'HOTWAX'.
NOTE: If the view does not return any records, the Feed file of HotWax will not generate, and logs the message, "No eligible returns to prepare Returns Financial Feed at ${nowDate}, not generating the HotWax Feed file."
If FinancialReturnItemsSyncQueue has eligible returns to prepare the feed then prepare the Return level details in the service:
billTo
returnAdjustments
customerPartyIdentifications
payments
Prepared the returnItems list i.e. fetched the returns items through eligible returns:
shipTo
productIdentifications
returnItemAdjustments
Prepare the isShippingChargesSent field and fetch Return level adjustments with return adjustment type 'RET_SHIPPING_ADJ', 'RET_SALES_TAX_ADJ' to create ReturnAdjustmentHistory records:
ReturnAdjustmentAndHistory View is created for the purpose to maintain the Return level Adjustments history which are sent as part of Feed to external systems.
The condition on the view is such that it will fetch Return level adjustments which are not sent to external systems.
The ReturnAdjustmentHistory record will be created for the Shipping Charges and Shipping Sales Tax.
If for a Return some items that are completed later and are eligible to appear in the next feed, then the isShippingChargesSent value will be sent as 'Y'.
Based on the value of isShippingChargesSent, the custom transformations can be prepared.
This is done so that financials can be done in the right way and order level adjustments are not computed multiple times which may cause discrepancies in the order totals when reconciliations are done.
NOTE: For now only Shipping Charges and Shipping Sales Tax are considered as the Order level Adjustments for which we are maintaining the history.
If FinancialReturnItemsSyncQueue has eligible returns to prepare feed then to prepare values of other fields as per the Chain Drive format, for each return item fetched from the first view, entity find is done on the second view, ReturnItemView.
The Return Level Adjustments list (shipping charges, shipping sales tax, etc) for the feed is prepared in the service.
The Return Item Level Adjustments list (return item sales tax, return item discount, etc) for the feed is prepared in the service.
NOTE: The specific amount for returnAdjustmentTypeIds from the Return Header Level Adjustments list and Return Item Level Adjustments list will be prepared in the Jolt Transform.
To Prepare total amount (TENDER_AMOUNT)
Logic used -> ReturnPrice * quantity + sum of the Item Level Adjustments
For TENDER_AMOUNT, there is the scenario: If the Return has three items and two of them are completed today and eligible for today's feed then in the feed TENDER_AMOUNT will be the sum(of amounts) of only these two items + shipping charges and shipping sales tax.
Next day if the third item will be completed and eligible for the feed then in the feed TENDER_AMOUNT will be the sum(of amounts) of only this item + shipping charges and shipping sales tax.
Note - This is part of special handling used the ReturnItemAndAdjustment view to prepare the TENDER_AMOUNT using the formula ReturnPrice * quantity + sum of the Item Level Adjustments(sum function used on the amounts in the view).
For preparing ShipToAddress, PostalAddressView is used with the condition on shipToContactMechId from ReturnItemView.
For preparing BillToAddress, first OrderContactMech is used to get contactMechId for the contactMechPurposeTypeId = 'BILLING_LOCATION'. Then PostalAddressView is used with a condition on contactMechId from OrderContactMech.
For maintaining the history of records sent as part of the Financial feed, the entity record for FinancialReturnHistory is created in the service itself.
returnId
ReturnItem.returnId
returnItemSeqId
ReturnItem.returnItemSeqId
entryDate
ReturnHeader.entryDate
returnDate
ReturnItem.returnId -> ReturnHeader.returnDate
returnChannelEnumId
ReturnHeader.returnChannelEnumId
orderSalesChannelEnumId
OrderHeader.salesChannelEnumId
orderSalesChannel
OrderHeader.salesChannelEnumId -> Enumeration.enumCode
orderId
ReturnItem.orderId
orderItemSeqId
ReturnItem.orderItemSeqId
returnItemAmountTotal
ReturnItem.returnItemPrice
statusId
ReturnItem.returnId, ReturnItem.returnItemSeqId -> ReturnStatus.statusId
completedDatetime
ReturnItem.returnId, ReturnItem.returnItemSeqId -> ReturnStatus.completedDatetime
productStoreId
ReturnItem.orderId -> OrderHeader.orderId
orderName
ReturnItem.orderId -> OrderHeader.orderName
productStoreExternalId
ReturnItem.orderId -> OrderHeader.productStoreId -> ProductStore.productStoreId
customerPartyId
ReturnItem.returnId -> ReturnHeader.fromPartyId
billTo
ReturnItem.orderId -> orderContactMech.contactMechId -> PostalAddress
billTo.countryGeoCode
orderContactMech.contactMechId -> PostalAddress.countryGeoId -> Geo.geoId
billTo.stateProvinceGeoCode
orderContactMech.contactMechId -> PostalAddress.stateGeoId -> Geo.geoId
billTo.contactMechId
orderContactMech.contactMechId -> PostalAddress.contactMechId
billTo.toName
orderContactMech.contactMechId -> PostalAddress.toName
billTo.attnName
orderContactMech.contactMechId -> PostalAddress.attnName
billTo.address1
orderContactMech.contactMechId -> PostalAddress.address1
billTo.address2
orderContactMech.contactMechId -> PostalAddress.address2
billTo.houseNumber
orderContactMech.contactMechId -> PostalAddress.houseNumber
billTo.houseNumberExt
orderContactMech.contactMechId -> PostalAddress.houseNumberExt
billTo.city
orderContactMech.contactMechId -> PostalAddress.city
billTo.cityGeoId
orderContactMech.contactMechId -> PostalAddress.cityGeoId
billTo.postalCode
orderContactMech.contactMechId -> PostalAddress.postalCode
billTo.postalCodeExt
orderContactMech.contactMechId -> PostalAddress.postalCodeExt
billTo.countryGeoId
orderContactMech.contactMechId -> PostalAddress.countryGeoId
billTo.stateProvinceGeoId
orderContactMech.contactMechId -> PostalAddress.stateProvinceGeoId
billTo.countyGeoId
orderContactMech.contactMechId -> PostalAddress.countyGeoId
billTo.municipalityGeoId
orderContactMech.contactMechId -> PostalAddress.municipalityGeoId
billTo.postalCodeGeoId
orderContactMech.contactMechId -> PostalAddress.postalCodeGeoId
billTo.geoPointId
orderContactMech.contactMechId -> PostalAddress.geoPointId
billTo.encodedAddressKey
orderContactMech.contactMechId -> PostalAddress.encodedAddressKey
isShippingChargesSent
Define the custom variable to identify shipping charges, shipping sales tax, and whether shipping adjustments were sent or not.
returnAdjustments
List of Return Level Adjustments
returnAdjustments.returnAdjustmentId
ReturnItem.returnId -> ReturnAdjustment.returnAdjustmentId
returnAdjustments.returnId
ReturnItem.returnId -> ReturnAdjustment.returnId
returnAdjustments.returnItemSeqId
ReturnItem.returnId -> ReturnAdjustment.returnItemSeqId
returnAdjustments.returnAdjustmentTypeId
ReturnItem.returnId -> ReturnAdjustment.returnAdjustmentTypeId
returnAdjustments.amount
ReturnItem.returnId -> ReturnAdjustment.amount
customerPartyIdentifications
List of the partyIdentifications
customerPartyIdentifications.partyId
ReturnItem.returnId -> ReturnHeader.fromPartyId -> PartyIdentification.partyId
customerPartyIdentifications.partyIdentificationTypeId
ReturnItem.returnId -> ReturnHeader.fromPartyId -> PartyIdentification.partyIdentificationTypeId
customerPartyIdentifications.idValue
ReturnItem.returnId -> ReturnHeader.fromPartyId -> PartyIdentification.idValue
customerPartyIdentifications.lastUpdatedStamp
ReturnItem.returnId -> ReturnHeader.fromPartyId -> PartyIdentification.lastUpdatedStamp
payments
List of the Payment related
payments.paymentMethodCode
ReturnItem.returnId -> ReturnItemResponse.orderPaymentPreferenceId -> OrderPaymentPreference.paymentMethodTypeId -> PaymentMethodType.paymentMethodCode
payments.createdDate
ReturnItem.returnId -> ReturnItemResponse.orderPaymentPreferenceId -> OrderPaymentPreference.createdDate
payments.paymentMethodTypeId
ReturnItem.returnId -> ReturnItemResponse.orderPaymentPreferenceId -> OrderPaymentPreference.paymentMethodTypeId -> PaymentMethodType.paymentMethodTypeId
payments.paymentMethodDescription
ReturnItem.returnId -> ReturnItemResponse.orderPaymentPreferenceId -> OrderPaymentPreference.paymentMethodTypeId -> PaymentMethodType.paymentMethodDescription
payments.statusId
ReturnItem.returnId -> ReturnItemResponse.orderPaymentPreferenceId -> OrderPaymentPreference.statusId
payments.amount
ReturnItem.returnId -> ReturnItemResponse.orderPaymentPreferenceId -> OrderPaymentPreference.amount
payments.orderId
ReturnItem.returnId -> OrderPaymentPreference.orderId
tenderAmount
ReturnItem.returnId -> ReturnAdjustment.amount (Return Price * Quantity + Return Item Adjustments)
returnItems
List of the return items.
returnItems.returnId
ReturnItem.returnId
returnItems.returnItemSeqId
ReturnItem.returnItemSeqId
returnItems.orderId
ReturnItem.orderId
returnItems.orderItemSeqId
ReturnItem.orderItemSeqId
returnItems.returnItemPrice
ReturnItem.returnItemPrice
returnItems.returnQuantity
ReturnItem.returnQuantity
returnItems.returnReasonId
ReturnItem.returnReasonId
returnItems.returnReasonNote
ReturnItem.reason
returnItems.orderItemRequestedShipMethTypeId
OrderItem.returnReasonId
returnItems.productId
ReturnItem.productId
returnItems.orderName
ReturnItem.orderId -> OrderHeader.orderName
returnItems.facilityExternalId
ReturnItem.returnId -> ReturnHeader.destinationFacilityId -> Facility.externalId
returnItems.facilityId
ReturnItem.returnId -> ReturnHeader.destinationFacilityId -> Facility.facilityId
returnItems.productStoreExternalId
ReturnItem.orderId -> OrderHeader.productStoreId -> ProductStore.externalId
returnItems.currencyUom
ReturnItem.returnId -> ReturnHeader.currencyUomId -> Uom.abbreviation
returnItems.customerPartyId
ReturnItem.returnId -> ReturnHeader.fromPartyId
returnItems.shipToContactMechId
ReturnItem.returnId -> ReturnHeader.originContactMechId
returnItems.shipTo
ReturnItem.orderId -> orderContactMech.contactMechId -> PostalAddress
returnItems.billToContactMechId
ReturnItem.orderId -> orderContactMech.contactMechId -> PostalAddress.contactMechId
returnItems.billTo
ReturnItem.orderId -> orderContactMech.contactMechId -> PostalAddress
Learn about the Returns Financial Feed, a JSON-formatted return-wise feed generated from HotWax Commerce OMS.
The Returns Financial Feed, generated from HotWax Commerce OMS, is a JSON-formatted feed containing details about returns created against orders, originating from both online and in-store channels. This feed facilitates financial reconciliation, particularly when integrating with third-party systems such as ERP.
The Returns financial feed is useful for retailers who use ERP for their accounting purposes and requires financial reconciliation during specific cycles. This feed provides the out-of-the-box data available from OMS, and retailers can use it as is or after transformation to ingest into external systems through file-based integration.
The Returns Financial Feeed Order Items feed has certain out-of-the-box customizations that allow users to generate the feed as per the requirements.
Parameter
Description
orderId
Filter return details for a specific order ID.
returnId
Filter return details for a specific return ID.
sinceReturnDate
Filter returns after a specific return date. Corresponds to the return date in HotWax Commerce.
sinceReturnCompletedDate
Filter returns completed in HotWax Commerce after a specific date. Corresponds to the completion date for return items in HotWax Commerce.
sinceEntryDate
Filter returns created after a specific date in HotWax Commerce. Corresponds to the entry date in HotWax Commerce.
productStoreIds
Sets the product store IDs to generate brand-specific feeds. For example, "WSC_STORE".
returnChannelEnumId
Identifies returns made from different channels such as e-commerce returns or in-store returns.
customParametersMap
Defines custom conditions, allowing flexibility in specifying new conditions. For example, {"returnReasonId_op": "empty", "returnReasonId_not": "Y"}.
optimize
Optimize the query or process for better performance.
The following attributes have been prepared in the feed:
returnId
Identifier for the return.
returnItemSeqId
Sequence ID for the return item.
entryDate
Date of entry for the return.
returnDate
Date of the return.
orderSalesChannelEnumId
Enum ID for the order sales channel.
orderSalesChannel
Sales channel for the order.
returnChannelEnumId
Enum ID for the return channel.
orderId
Identifier for the order.
orderItemSeqId
Sequence ID for the order item.
returnItemAmountTotal
Total amount for the return item.
statusId
Identifier for the status.
completedDatetime
Date and time when the return was completed.
productStoreId
Identifier for the product store.
orderName
Name of the order.
productStoreExternalId
External ID for the product store.
customerPartyId
Identifier for the customer party.
billTo
Object containing billing address information.
isShippingChargesSent
Flag indicating if shipping charges were sent.
returnAdjustments
Array of adjustments related to the return.
customerPartyIdentifications
Array of identifications for the customer party.
tenderAmount
Amount tendered for the return.
payments
Array of payments related to the return.
returnItems
Array of items being returned.
Nested Fields within billTo:
houseNumberExt
Extension for the house number.
address2
Additional address information.
postalCode
Postal code of the address.
...
More fields for the billing address.
Nested Fields within returnAdjustments:
customerReferenceId
Identifier for customer reference.
amount
Amount of the adjustment.
description
Description of the adjustment.
...
More fields for the return adjustments.
Nested Fields within customerPartyIdentifications:
partyId
Identifier for the party.
idValue
Value of the identification.
...
More fields for the customer party identifications.
Nested Fields within payments:
paymentMethodTypeId
Type of payment method.
paymentMethodDescription
Description of the payment method.
statusId
Identifier for the status.
...
More fields for the payments.
Nested Fields within returnItems:
returnId
Identifier for the return.
returnItemSeqId
Sequence ID for the return item.
orderId
Identifier for the order.
...
More fields for the return items.
Nested Fields within shipTo:
houseNumberExt
Extension for the house number.
contactMechId
Identifier for the contact mechanism.
postalCode
Postal code of the address.
...
More fields for the shipping address.
Nested Fields within productIdentifications:
productId
Identifier for the product.
goodIdentificationTypeId
Type of good identification.
idValue
Value of the identification.
...
More fields for the product identifications.
Nested Fields within returnItemAdjustments:
customerReferenceId
Identifier for customer reference.
amount
Amount of the adjustment.
description
Description of the adjustment.
...
More fields for the return item adjustments.