Clarification on refund and return items within the same node

Products and Orders APIs
1

Hello.

I have a query regarding the structure of our GraphQL response for an order. For a single order node, the query results show associated products, including items that were refunded or returned. I want to confirm that when refund and return objects appear under the same order node, they correspond to refund/return events for that specific order.

For example, in our response we see:

  • Order ID: #12345
    • Lineitem A
    • Lineitem B (Refunded)
    • Lineitem C (Returned)

Could you confirm that this structure is expected, meaning refund and return entries within the same order node always refer to that order’s own refund/return activities? If there are recommended query patterns to verify this more clearly, please let me know.

Thank you!

request example

===========================================

{

“query”: "query {

orders(first: 100, query: \“created_at:>=2025-11-05 AND created_at:<=2025-11-05\” ) {

pageInfo {

    hasNextPage

    endCursor

}

edges {

  node {

    id                  # 주문번호

    name

    number

    createdAt           # 주문생성일시

    totalPrice          # 총 결제 금액

    note

    customer {           # 구매자 정보

      displayName         # 구매자

      email               # 이메일

      defaultPhoneNumber {

        phoneNumber      # 연락처

      }

    }

    lineItems(first: 20) {    # 구매 옵션별 주문

      edges {

        node {

          id

          title          # 상품명

          variantTitle   # 옵션명

          quantity       # 주문 수량

          originalUnitPrice   # 옵션단가

          variant {

            product {

              id      # 상품(Product) 자체 정보

              title   # 상품(Product)의 대표 이름

            }

          }

        }

      }

    }

    shippingAddress {    # 주문 배송지

      name              # 고객의 전체 이름 (firstName + lastName 조합)

      phone             # 고객의 전화번호

      zip               # 우편번호

      address1          # 주소1

      address2          # 주소2

      formattedArea     # city, province, country를 콤마로 연결한 문자열

      #city              # 도시/구/군/동 이름

      #province          # 지역/주/도/구 

      #country           # 국가명

    }

    shippingLine {

      title           # 배송 방법명 (예: 일반택배)

      discountedPriceSet {

        shopMoney {

          amount        # 배송비 금액

          currencyCode  # 통화단위

        }

      }

    }

    refunds(first: 50) {          # 환불 주문

        refundLineItems(first: 20) {

            edges {

                node {

                    lineItem {

                        id

                    }

                }

            }

        }

    }

    returns(first: 50) {             # 반품 주문

        nodes {

            id

            name

            order {

                id

                lineItems(first:20) {

                    edges {

                        node {

                            id

                        }

                    }

                }

            }

        }

    }

    displayFinancialStatus

    displayFulfillmentStatus

    closed

  }

}

}

}",

“variables”: {}

}

2

Hi @user160

From digging into this, it does appear that your understanding is correct: when you query an order node in Shopify’s Admin GraphQL API, the refunds and returns objects that appear under that order node always refer to refund and return events for that specific order.

  • The Refund object is always associated with a specific Order via its order field. This means any refund listed under an order node is for that order only.
  • The Return object is also associated with a specific Order via its order field. Returns listed under an order node are for that order only.
  • Refunds can optionally be linked to a Return if the refund was initiated through the returns process, but both are always scoped to the order in which they appear.

You could also explicitly request the order ID within each refund and return object to confirm the association, it would look something like this:

query OrdersWithRefundsAndReturns {
  orders(first: 1, query: "name:#12345") {
    edges {
      node {
        id
        name
        refunds(first: 10) {
          edges {
            node {
              id
              order {
                id
              }
            }
          }
        }
        returns(first: 10) {
          nodes {
            id
            order {
              id
            }
          }
        }
      }
    }
  }
}

Hope this helps!