Handling returns

A return can be created when the customer initiates it from My pages, and lists the order rows and quantities being returned.

Get returns

Use returnConnection to fetch returns. You can filter by return IDs, order IDs or customer IDs, and sort by ID or CREATED_AT. With an ADMIN token you receive returns for all customers. With a CUSTOMER token you only receive the logged-in customer's own returns.

The example below fetches the two most recent returns for an order.

Request:

query getReturns {
  returnConnection(
    first: 2
    filter: {orderIds: [338]}
    sort: [{field: CREATED_AT, direction: DESC}]
  ) {
    edges {
      node {
        id
        orderId
        type
        createdAt
        status {
          value
        }
        rows {
          orderRowId
          quantity
          reason {
            value
          }
        }
      }
    }
    pageInfo {
      endCursor
    }
    totalCount
  }
}

Response:

{
  "data": {
    "returnConnection": {
      "edges": [
        {
          "node": {
            "id": 1207,
            "orderId": 338,
            "type": "RETURN",
            "createdAt": "2024-05-14T10:22:41Z",
            "status": [
              {
                "value": "Received"
              }
            ],
            "rows": [
              {
                "orderRowId": 668,
                "quantity": 1,
                "reason": [
                  {
                    "value": "Changed my mind"
                  }
                ]
              }
            ]
          }
        },
        {
          "node": {
            "id": 1198,
            "orderId": 338,
            "type": "CLAIM",
            "createdAt": "2024-05-09T08:03:17Z",
            "status": [
              {
                "value": "Processed"
              }
            ],
            "rows": [
              {
                "orderRowId": 670,
                "quantity": 2,
                "reason": [
                  {
                    "value": "Damaged on arrival"
                  }
                ]
              }
            ]
          }
        }
      ],
      "pageInfo": {
        "endCursor": "1198"
      },
      "totalCount": 2
    }
  }
}

Update return status

Use batchUpdateReturns to update the status of one or more returns. This requires an ADMIN token.

Updating the status of a return can, in some cases, update the payment and create a refund. It can also credit the customer through the payment provider.

Set triggerNotification to true to send the emails configured in the message center for the status change. If none are configured, nothing is sent.

The call is asynchronous, and the query for jobStatus should be used to check the result. In most cases, you can expect the job to be processed within a few seconds.

Request:

mutation updateReturnStatus {
  batchUpdateReturns(
    input: [{id: 1207, status: 3}]
    options: {triggerNotification: true}
  ) {
    id
    status
  }
}

Response:

{
  "data": {
    "batchUpdateReturns": {
      "id": 512,
      "status": "waiting"
    }
  }
}

Check status of your job

Request:

query status {
  jobStatus(id: 512) {
    id
    status
  }
}

Response:

{
  "data": {
    "jobStatus": {
      "id": 512,
      "status": "completed"
    }
  }
}