Choose a version:

refund

query

Requires read_orders access scope or read_marketplace_orders access scope.

Retrieves a refund by its ID. A refund represents a financial record of money returned to a customer from an order. It provides a comprehensive view of all refunded amounts, transactions, and restocking instructions associated with returning products or correcting order issues.

Use the refund query to retrieve information associated with the following workflows:

Displaying refund details in order management interfaces
Building customer service tools for reviewing refund history
Creating reports on refunded amounts and reasons
Auditing refund transactions and payment gateway records
Tracking inventory impacts from refunded items

A refund is associated with an order and includes refund line items that specify which items were refunded. Each refund processes through order transactions that handle the actual money transfer back to the customer.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of the Refund to return.

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to RefundRefund

•Refund

The Refund object represents a financial record of money returned to a customer from an order. It provides a comprehensive view of all refunded amounts, transactions, and restocking instructions associated with returning products or correcting order issues.

The Refund object provides information to:

Process customer returns and issue payments back to customers
Handle partial or full refunds for line items with optional inventory restocking
Refund shipping costs, duties, and additional fees
Issue store credit refunds as an alternative to original payment method returns
Track and reconcile all financial transactions related to refunds

Each Refund object maintains detailed records of what was refunded, how much was refunded, which payment transactions were involved, and any inventory restocking that occurred. The refund can include multiple components such as product line items, shipping charges, taxes, duties, and additional fees, all calculated with proper currency handling for international orders.

Refunds are always associated with an order and can optionally be linked to a return if the refund was initiated through the returns process. The refund tracks both the presentment currency (what the customer sees) and the shop currency for accurate financial reporting.

Note

The existence of a Refund object doesn't guarantee that the money has been returned to the customer. The actual financial processing happens through associated OrderTransaction objects, which can be in various states, such as pending, processing, success, or failure. To determine if money has actually been refunded, check the status of the associated transactions.

Learn more about managing returns, refunding duties, and processing refunds.

Anchor to createdAtcreatedAt

•DateTime

The date and time when the refund was created.

Anchor to dutiesduties

•[RefundDuty!]

A list of the refunded duties as part of this refund.

Anchor to idid

•ID!

non-null

A globally-unique ID.

Anchor to legacyResourceIdlegacyResourceId

•UnsignedInt64!

non-null

The ID of the corresponding resource in the REST Admin API.

Anchor to notenote

•String

The optional note associated with the refund.

Anchor to orderorder

•Order!

non-null

The order associated with the refund.

Anchor to orderAdjustmentsorderAdjustments

•OrderAdjustmentConnection!

non-null

The order adjustments that are attached with the refund.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to processedAtprocessedAt

•DateTime!

non-null

The date and time when the refund was processed.

Anchor to refundLineItemsrefundLineItems

•RefundLineItemConnection!

non-null

The RefundLineItem resources attached to the refund.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to refundShippingLinesrefundShippingLines

•RefundShippingLineConnection!

non-null

The RefundShippingLine resources attached to the refund.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to returnreturn

•Return

The return associated with the refund.

Anchor to staffMemberstaffMember

•StaffMember

The staff member who created the refund.

Anchor to totalRefundedSettotalRefundedSet

•MoneyBag!

non-null

The total amount across all transactions for the refund, in shop and presentment currencies.

Anchor to transactionstransactions

•OrderTransactionConnection!

non-null

The transactions associated with the refund.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to updatedAtupdatedAt

•DateTime!

non-null

The date and time when the refund was updated.

Anchor to totalRefundedtotalRefunded

•MoneyV2!

non-nullDeprecated

Was this section helpful?

Examples

Get refund duties

Description

The following query retrieves a refund by its ID and returns the refund duties.

Query

query refund($input: ID!) {
  refund(id: $input) {
    duties {
      originalDuty {
        countryCodeOfOrigin
      }
      amountSet {
        shopMoney {
          amount
        }
      }
    }
  }
}

Variables

{
  "input": "gid://shopify/Refund/850600470"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query refund($input: ID!) { refund(id: $input) { duties { originalDuty { countryCodeOfOrigin } amountSet { shopMoney { amount } } } } }",
 "variables": {
    "input": "gid://shopify/Refund/850600470"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query refund($input: ID!) {
    refund(id: $input) {
      duties {
        originalDuty {
          countryCodeOfOrigin
        }
        amountSet {
          shopMoney {
            amount
          }
        }
      }
    }
  }`,
  {
    variables: {
        "input": "gid://shopify/Refund/850600470"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query refund($input: ID!) {
    refund(id: $input) {
      duties {
        originalDuty {
          countryCodeOfOrigin
        }
        amountSet {
          shopMoney {
            amount
          }
        }
      }
    }
  }
QUERY

variables = {
  "input": "gid://shopify/Refund/850600470"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query refund($input: ID!) {
      refund(id: $input) {
        duties {
          originalDuty {
            countryCodeOfOrigin
          }
          amountSet {
            shopMoney {
              amount
            }
          }
        }
      }
    }`,
    "variables": {
        "input": "gid://shopify/Refund/850600470"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'query refund($input: ID!) {
  refund(id: $input) {
    duties {
      originalDuty {
        countryCodeOfOrigin
      }
      amountSet {
        shopMoney {
          amount
        }
      }
    }
  }
}' \
--variables \
'{
  "input": "gid://shopify/Refund/850600470"
}'

Response

{
  "refund": {
    "duties": [
      {
        "originalDuty": {
          "countryCodeOfOrigin": "US"
        },
        "amountSet": {
          "shopMoney": {
            "amount": "6.0"
          }
        }
      }
    ]
  }
}

Get the total refunded amount

Description

The following query retrieves a refund by its ID and returns the total refunded amount.

Query

query refund($input: ID!) {
  refund(id: $input) {
    totalRefundedSet {
      shopMoney {
        amount
        currencyCode
      }
    }
  }
}

Variables

{
  "input": "gid://shopify/Refund/196417871"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query refund($input: ID!) { refund(id: $input) { totalRefundedSet { shopMoney { amount currencyCode } } } }",
 "variables": {
    "input": "gid://shopify/Refund/196417871"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query refund($input: ID!) {
    refund(id: $input) {
      totalRefundedSet {
        shopMoney {
          amount
          currencyCode
        }
      }
    }
  }`,
  {
    variables: {
        "input": "gid://shopify/Refund/196417871"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query refund($input: ID!) {
    refund(id: $input) {
      totalRefundedSet {
        shopMoney {
          amount
          currencyCode
        }
      }
    }
  }
QUERY

variables = {
  "input": "gid://shopify/Refund/196417871"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query refund($input: ID!) {
      refund(id: $input) {
        totalRefundedSet {
          shopMoney {
            amount
            currencyCode
          }
        }
      }
    }`,
    "variables": {
        "input": "gid://shopify/Refund/196417871"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'query refund($input: ID!) {
  refund(id: $input) {
    totalRefundedSet {
      shopMoney {
        amount
        currencyCode
      }
    }
  }
}' \
--variables \
'{
  "input": "gid://shopify/Refund/196417871"
}'

Response

{
  "refund": {
    "totalRefundedSet": {
      "shopMoney": {
        "amount": "5.75",
        "currencyCode": "USD"
      }
    }
  }
}

Retrieves a specific refund

Query

query RefundShow($id: ID!) {
  refund(id: $id) {
    id
    note
    totalRefundedSet {
      presentmentMoney {
        amount
        currencyCode
      }
    }
  }
}

Variables

{
  "id": "gid://shopify/Refund/196417871"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query RefundShow($id: ID!) { refund(id: $id) { id note totalRefundedSet { presentmentMoney { amount currencyCode } } } }",
 "variables": {
    "id": "gid://shopify/Refund/196417871"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query RefundShow($id: ID!) {
    refund(id: $id) {
      id
      note
      totalRefundedSet {
        presentmentMoney {
          amount
          currencyCode
        }
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Refund/196417871"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query RefundShow($id: ID!) {
    refund(id: $id) {
      id
      note
      totalRefundedSet {
        presentmentMoney {
          amount
          currencyCode
        }
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Refund/196417871"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query RefundShow($id: ID!) {
      refund(id: $id) {
        id
        note
        totalRefundedSet {
          presentmentMoney {
            amount
            currencyCode
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Refund/196417871"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'query RefundShow($id: ID!) {
  refund(id: $id) {
    id
    note
    totalRefundedSet {
      presentmentMoney {
        amount
        currencyCode
      }
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Refund/196417871"
}'

Response

{
  "refund": {
    "id": "gid://shopify/Refund/196417871",
    "note": "free shipping",
    "totalRefundedSet": {
      "presentmentMoney": {
        "amount": "5.75",
        "currencyCode": "USD"
      }
    }
  }
}

Examples

Open in GraphiQL

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

query refund($input: ID!) {

refund(id: $input) {

duties {

originalDuty {

countryCodeOfOrigin

}

amountSet {

shopMoney {

amount

}

}`,

{

variables: {

"input": "gid://shopify/Refund/850600470"

);

const json = await response.json();

return json.data;

}

GQL

query refund($input: ID!) {
  refund(id: $input) {
    duties {
      originalDuty {
        countryCodeOfOrigin
      }
      amountSet {
        shopMoney {
          amount
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query refund($input: ID!) { refund(id: $input) { duties { originalDuty { countryCodeOfOrigin } amountSet { shopMoney { amount } } } } }",
 "variables": {
    "input": "gid://shopify/Refund/850600470"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query refund($input: ID!) {
    refund(id: $input) {
      duties {
        originalDuty {
          countryCodeOfOrigin
        }
        amountSet {
          shopMoney {
            amount
          }
        }
      }
    }
  }`,
  {
    variables: {
        "input": "gid://shopify/Refund/850600470"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query refund($input: ID!) {
      refund(id: $input) {
        duties {
          originalDuty {
            countryCodeOfOrigin
          }
          amountSet {
            shopMoney {
              amount
            }
          }
        }
      }
    }`,
    "variables": {
        "input": "gid://shopify/Refund/850600470"
    },
  },
});

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query refund($input: ID!) {
    refund(id: $input) {
      duties {
        originalDuty {
          countryCodeOfOrigin
        }
        amountSet {
          shopMoney {
            amount
          }
        }
      }
    }
  }
QUERY

variables = {
  "input": "gid://shopify/Refund/850600470"
}

response = client.query(query: query, variables: variables)

Shopify CLI

shopify app execute \
--query \
'query refund($input: ID!) {
  refund(id: $input) {
    duties {
      originalDuty {
        countryCodeOfOrigin
      }
      amountSet {
        shopMoney {
          amount
        }
      }
    }
  }
}' \
--variables \
'{
  "input": "gid://shopify/Refund/850600470"
}'

Input variables

JSON

{

"input": "gid://shopify/Refund/850600470"

}

Response

JSON

{

"refund": {

"duties": [

{

"originalDuty": {

"countryCodeOfOrigin": "US"

"amountSet": {

"shopMoney": {

"amount": "6.0"

}

]

}