requestReturn mutation

Magento Commerce only

The content on this page is for Magento Commerce only. Learn more

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:

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