requestReturn mutation
Magento Commerce only
The requestReturn
mutation initiates a buyer’s request to return an item for replacement or refund. The merchant subsequently decides whether to accept or reject the request.
The following examples illustrate how to retrieve the order ID and item ID values needed to run the requestReturn
mutation:
- Retrieve a summary of the customer’s order history
- Retrieve detailed information about a specific order
Use the storeConfig
query with the returns_enabled
attribute to determine whether returned merchandise authorization (RMAs) are enabled.
Syntax
1
2
3
mutation {
requestReturn(input: RequestReturnInput!): RequestReturnOutput
}
Example usage
The following example requests a product return. At this point, the merchant hasn’t taken action, but the response acknowledges the request was received.
Request:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
mutation{
requestReturn(input: {
order_uid: "NQ=="
contact_email: "test1@example.com"
comment_text: "I want to return the shirt because I don't like the texture of the fabric"
items: {
order_item_uid: "MTE="
quantity_to_return: 1
}
}){
return {
uid
items {
uid
status
request_quantity
quantity
order_item {
id
eligible_for_return
product_sku
product_sku
product_type
quantity_returned
status
}
}
number
status
comments {
uid
author_name
text
created_at
}
customer {
firstname
lastname
email
}
}
}
}
Response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
"data": {
"requestReturn": {
"return": {
"uid": "Mw==",
"items": [
{
"uid": "Mw==",
"status": "PENDING",
"request_quantity": 1,
"quantity": 0,
"order_item": {
"id": "MTE=",
"eligible_for_return": true,
"product_sku": "MS09-M-Red",
"product_type": "configurable",
"quantity_returned": 0,
"status": "Shipped"
}
}
],
"number": "000000003",
"status": "PENDING",
"comments": [
{
"uid": "NQ==",
"author_name": "Customer Service",
"text": "We placed your Return request.",
"created_at": "2020-11-19 18:20:28"
},
{
"uid": "Ng==",
"author_name": "Bob Loblaw",
"text": "I want to return the shirt because I don't like the texture of the fabric",
"created_at": "2020-11-19 18:20:28"
}
],
"customer": {
"firstname": "Bob",
"lastname": "Loblaw",
"email": "test1@example.com"
}
}
}
}
}
Input attributes
The requestReturn
mutation requires the following input.
Attribute | Data Type | Description |
---|---|---|
comment_text |
String | Text the buyer entered that describes the reason for the refund request |
contact_email |
String | An email address the buyer enters to receive notifications about the status of the return |
items |
[RequestReturnItemInput!]! | An array of items to be returned |
order_uid |
ID! | The unique ID for an Order object |
RequestReturnItemInput attributes
The RequestReturnItemInput object
Attribute | Data Type | Description |
---|---|---|
entered_custom_attributes |
[EnteredCustomAttributeInput!] | Contains details about a custom attribute that was entered, such as text or a file |
order_item_uid |
ID! | The unique ID for an OrderItemInterface object |
quantity_to_return |
Float! | The quantity of the item to be returned |
selected_custom_attributes |
[SelectedCustomAttributeInput!] | An array of selected custom option IDs associated with the item to be returned. For example, the IDs for the selected color and size of a configurable product |
EnteredCustomAttributeInput attributes
The EnteredCustomAttributeInput object
Attribute | Data Type | Description |
---|---|---|
attribute_code |
String! | A string that identifies the entered custom attribute |
value |
String! | The text or other entered value |
SelectedCustomAttributeInput attributes
The SelectedCustomAttributeInput object
Attribute | Data Type | Description
— | — | —
attribute_code
| String! | A string that identifies the selected attribute
value
| ID! | The unique ID for a CustomAttribute
object
Output attributes
The RequestReturnOutput
object can contain the following attributes.
Attribute | Data Type | Description |
---|---|---|
return |
Return | Contains details about a single return request”) |
returns(pageSize, currentPage) |
Returns | Contains an array of return requests |
Return attributes
The Return
object can contain the following attributes:
Attribute | Data Type | Description |
---|---|---|
available_shipping_carriers |
[ReturnShippingCarrier] | A list of shipping carriers available for returns |
comments |
[ReturnComment] | A list of comments posted for the return request |
created_at |
String! | The date the return was requested |
customer_email |
String! | Email of the person who created the return request |
customer |
ReturnCustomer | The name of the person who requested the return |
items |
[ReturnItem] | A list of items being returned |
number |
String! | Human-readable return number |
order |
CustomerOrder | The order associated with the return |
shipping |
ReturnShipping | Shipping information for the return |
status |
ReturnStatus | An enum indicating the status of the return request. Possible values are APPROVED, AUTHORIZED, CLOSED, DENIED, PARTIALLY_APPROVED, PARTIALLY_AUTHORIZED, PARTIALLY_RECEIVED, PARTIALLY_REJECTED, PENDING, PROCESSED_AND_CLOSED, RECEIVED, and REJECTED |
uid |
ID! | The unique ID of a Return object |
ReturnComment attributes
The ReturnComment object provides details about an individual comment in a refund request. Comments can be added by a customer or the merchant.
Attribute | Data Type | Description |
---|---|---|
author_name |
String! | The name or author who posted the comment |
created_at |
String! | The date and time the comment was posted |
text |
String! | The contents of the comment |
uid |
ID! | The unique ID of a ReturnComment object |
ReturnCustomAttribute attributes
Attribute | Data Type | Description |
---|---|---|
label |
String! | A description of the attribute |
uid |
ID! | The unique ID of a ReturnCustomAttribute attribute |
value |
String! | A JSON-encoded value of the attribute |
ReturnCustomer attributes
The ReturnCustomer object contains information about the person requesting a return.
Attribute | Data Type | Description |
---|---|---|
email |
String! | The email address of the refund requester |
firstname |
String | The first name of the refund requester |
lastname |
String | The last name of the refund requester |
ReturnItem attributes
The ReturnItem object provides details about an individual item in a return request.
Attribute | Data Type | Description |
---|---|---|
custom_attributes |
[ReturnCustomAttribute] | Return item custom attributes that are visible on the storefront |
order_item |
OrderItemInterface! | Provides access to the product being returned, including information about selected and entered options |
quantity |
Float! | The quantity of the item the merchant authorized to be returned |
request_quantity |
Float! | The quantity of the item requested to be returned |
status |
ReturnItemStatus! | An enum indicating the return status of the item. Possible values are APPROVED, AUTHORIZED, DENIED, PENDING, RECEIVED, and REJECTED |
uid |
ID! | The unique ID of an item of a Return object |
ReturnShipping attributes
The ReturnShipping object can contain the merchant’s shipping address and tracking information.
Attribute | Data Type | Description |
---|---|---|
address |
ReturnShippingAddress | The merchant-defined return shipping address |
tracking(uid: ID) |
[ReturnShippingTracking] | The unique ID for a ReturnShippingTracking object. If a single UID is specified, contains a single tracking record. Otherwise, contains all tracking information |
ReturnShippingAddress attributes
The ReturnShippingAddress object defines the merchant address for receiving returned items.
Attribute | Data Type | Description |
---|---|---|
city |
String! | The city for product returns |
contact_name |
String | The merchant’s contact person |
country |
Country! | An object that defines the country for product returns |
postcode |
String! | The postal code for product returns |
region |
Region! | An object that defines the state or province for product returns |
street |
[String]! | The street address for product returns |
telephone |
String | The telephone number for product returns |
ReturnShippingCarrier attributes
The ReturnShippingCarrier object contains details about the shipping carrier used to return a product.
Attribute | Data Type | Description |
---|---|---|
label |
String! | A description of the shipping carrier |
uid |
ID! | The unique ID of a ReturnShippingCarrier object |
ReturnShippingTracking attributes
The ReturnShippingTracking object contains tracking information for an approved return.
Attribute | Data Type | Description |
---|---|---|
carrier |
ReturnShippingCarrier! | Contains details of a shipping carrier |
status |
ReturnShippingTrackingStatus | Contains details about the status of a shipment |
tracking_number |
String! | A tracking number assigned by the carrier |
uid |
ID! | The unique ID assigned of a ReturnShippingTracking object |
ReturnShippingTrackingStatus attributes
The ReturnShippingTrackingStatus object contains tracking status information for an approved return.
Attribute | Data Type | Description |
---|---|---|
text |
String! | Text that describes the status |
type |
ReturnShippingTrackingStatusType! | An enum indicating whether the status type is INFORMATIONAL or an ERROR |
Returns attributes
The Returns
object contains an array of Return
objects and pagination information.
Attribute | Data Type | Description |
---|---|---|
items |
[Return] | A list of return requests |
page_info SearchResultPageInfo |
Pagination metadata | |
total_count |
Int | The total number of return requests |