requestReturn mutation

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.

RequestReturnItemInput attributes

The RequestReturnItemInput object

EnteredCustomAttributeInput attributes

The EnteredCustomAttributeInput object

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.

Return attributes

The Return object can contain the following attributes:

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.

ReturnCustomAttribute attributes

ReturnCustomer attributes

The ReturnCustomer object contains information about the person requesting a return.

ReturnItem attributes

The ReturnItem object provides details about an individual item in a return request.

ReturnShipping attributes

The ReturnShipping object can contain the merchant’s shipping address and tracking information.

ReturnShippingAddress attributes

The ReturnShippingAddress object defines the merchant address for receiving returned items.

ReturnShippingCarrier attributes

The ReturnShippingCarrier object contains details about the shipping carrier used to return a product.

ReturnShippingTracking attributes

The ReturnShippingTracking object contains tracking information for an approved return.

ReturnShippingTrackingStatus attributes

The ReturnShippingTrackingStatus object contains tracking status information for an approved return.

Returns attributes

The Returns object contains an array of Return objects and pagination information.

Related topics

• addReturnComment mutation
• addReturnTracking mutation
• removeReturnTracking mutation