> For the complete documentation index, see [llms.txt](https://docs.hotwax.co/documents/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hotwax.co/documents/integrate-with-hotwax/hotwax-commerce-api-and-data-feeds/returns/create-return.md).
# Create Return
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.
## Request
### Endpoint
* POST: `https://{host}/api/createReturn`
### Header
* Content-Type: application/json
### Body
```
{
"payLoad": {
"externalId": "",
"type": "",
"returnDate": "",
"customerId": "",
"externalCustomerId": "",
"companyId": "",
"companyExternalId": "",
"status": "",
"currencyCode": "",
"grandTotal": ,
"tags": [ ],
"note": "",
"returnIdentifications": [
{
"returnIdentificationTypeId": "",
"returnIdentificationDesc": "",
"idValue": ""
}
],
"shipFrom": {
"postalAddress": {
"id": "",
"externalId": ""
}
},
"shipTo": {
"facilityId": ""
},
"items": [
{
"id": "",
"sku": "",
"idType": "",
"idValue": "",
"itemExternalId": "",
"itemSeqId": "",
"itemTypeId": "",
"status": "",
"orderId": "",
"orderExternalId": "",
"orderName": "",
"orderItemSeqId": "",
"orderItemExternalId": "",
"quantity": ,
"reason": "",
"returnType": "",
"restockType": "",
"price": ,
"itemAdjustments": [
{
"returnAdjustmentTypeId": "",
"amount":
},
{
"type": "",
"comments": "",
"description": "",
"amount": "",
"sourcePercentage": ""
}
]
}
],
"returnAdjustment": [
{
"orderId": "",
"orderExternalId": "",
"id": "",
"type": "",
"comments": "",
"description": "",
"amount": "",
"sourcePercentage": ""
}
]
}
}
```
**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.
| Return Adjustment Type | Description |
| ---------------------- | ------------------------------------ |
| 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 |
## Return channels
The two return channels are as follows:
| Enum Id | Enum Type Id | Description | Enum Name | Sequence Id |
| ------------------ | --------------- | ------------------- | --------- | ----------- |
| ECOM\_RTN\_CHANNEL | RETURN\_CHANNEL | Ecom Return Channel | | 01 |
| POS\_RTN\_CHANNEL | RETURN\_CHANNEL | POS Return Channel | | 02 |
Sample response
```json
{
"payLoad": {
"externalId": "5758438048028",
"type": "CUSTOMER_RETURN",
"customerId": "10317",
"externalCustomerId": "",
"companyId": "COMPANY",
"companyExternalId": "",
"status": "RETURN_RECEIVED",
"currencyCode": "CAD",
"grandTotal": 150.01,
"returnIdentifications": [
{
"returnIdentificationTypeId": "SHOPIFY_RTN_ID",
"returnIdentificationDesc": "MarketPlace Return",
"idValue": "5758438048028"
}
],
"shipFrom": {
"postalAddress": {
"id": "",
"externalId": ""
}
},
"shipTo": {
"facilityId": "KITST"
},
"items": [
{
"id": "10243",
"sku": "",
"idType": "UPCA",
"idValue": "1110352-7AY-M",
"itemExternalId": "",
"itemSeqId": "",
"itemTypeId": "PRODUCT_ORDER_ITEM",
"status": "RETURN_RECEIVED",
"orderId": "FAO11428",
"orderExternalId": "5758438048028",
"orderName": "101010236",
"orderItemSeqId": "00101",
"orderItemExternalId": "",
"quantity": 1,
"price": 89.5
}
]
}
}
```
## Response
### Header
* Content-Type: application/json
### Body
The response will include all the parameters provided in the request body, along with any error messages and login information.
Sample response
```json
_LOGIN_PASSED_": "T{
"_ERROR_MESSAGE_": "",
"payLoad": {
"externalId": "5758438048028",
"type": "CUSTOMER_RETURN",
"customerId": "10317",
"externalCustomerId": "",
"companyId": "COMPANY",
"companyExternalId": "",
"status": "RETURN_RECEIVED",
"currencyCode": "CAD",
"grandTotal": 150.01,
"returnIdentifications": [
{
"returnIdentificationTypeId": "SHOPIFY_RTN_ID",
"returnIdentificationDesc": "MarketPlace Return",
"idValue": "5758438048028"
}
],
"shipFrom": {
"postalAddress": {
"id": "",
"externalId": ""
}
},
"shipTo": {
"facilityId": "KITST"
},
"items": [
{
"id": "10243",
"sku": "",
"idType": "UPCA",
"idValue": "1110352-7AY-M",
"itemExternalId": "",
"itemSeqId": "",
"itemTypeId": "PRODUCT_ORDER_ITEM",
"status": "RETURN_RECEIVED",
"orderId": "FAO11428",
"orderExternalId": "5758438048028",
"orderName": "101010236",
"orderItemSeqId": "00101",
"orderItemExternalId": "",
"quantity": 1,
"price": 89.5
}
]
},
"USERNAME": "hotwax.user",
"RUE"
}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.hotwax.co/documents/integrate-with-hotwax/hotwax-commerce-api-and-data-feeds/returns/create-return.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.