Choose a version:

refundCreate

mutation

Requires orders access scope, marketplace_orders access scope or buyer_membership_orders access scope.

Creates a refund for an order, allowing you to process returns and issue payments back to customers.

Use the refundCreate mutation to programmatically process refunds in scenarios where you need to return money to customers, such as when handling returns, processing chargebacks, or correcting order errors.

The refundCreate mutation supports various refund scenarios:

Refunding line items with optional restocking
Refunding shipping costs
Refunding duties and import taxes
Refunding additional fees
Processing refunds through different payment methods
Issuing store credit refunds (when enabled)

You can create both full and partial refunds, and optionally allow over-refunding in specific cases. The mutation also supports idempotent requests to safely retry failed refund attempts.

After creating a refund, you can track its status and details through the order's refunds field. The refund is associated with the order and can be used for reporting and reconciliation purposes.

Learn more about managing returns and refunding duties.

Note

The refunding behavior of the refundCreate mutation is similar to the refundReturn mutation. The key difference is that the refundCreate mutation lets you to specify restocking behavior for line items, whereas the returnRefund mutation focuses solely on handling the financial refund without any restocking input.

Arguments

Anchor to inputinput •RefundInput!required: The input fields that are used in the mutation for creating a refund.

Was this section helpful?

Anchor to RefundCreatePayload returnsRefundCreatePayload returns

Anchor to orderorder •Order: The order associated with the created refund.
Anchor to refundrefund •Refund: The created refund.
Anchor to userErrorsuserErrors •[UserError!]!non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Create a refund with a note and transaction, then return the total refund amount across all transactions
Create a refund with shipping partially refunded. Then, return the total refund amount and information about the first two transactions.
Creates a refund
refundCreate reference

Examples

Open in GraphiQL

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

const response = await admin.graphql(

`#graphql

mutation M($input: RefundInput!) {

refundCreate(input: $input) {

userErrors {

field

message

}

refund {

note

totalRefundedSet {

presentmentMoney {

amount

}

}`,

{

variables: {

"input": {

"orderId": "gid://shopify/Order/734509473",

"note": "Want to exchange for a different item",

"refundLineItems": [

{

"lineItemId": "gid://shopify/LineItem/25746870",

"quantity": 2

}

"transactions": [

{

"orderId": "gid://shopify/Order/734509473",

"gateway": "foo",

"kind": "REFUND",

"amount": "10.0",

"parentId": "gid://shopify/OrderTransaction/723599266"

}

]

}

);

const data = await response.json();

mutation M($input: RefundInput!) {
  refundCreate(input: $input) {
    userErrors {
      field
      message
    }
    refund {
      id
      note
      totalRefundedSet {
        presentmentMoney {
          amount
        }
      }
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation M($input: RefundInput!) { refundCreate(input: $input) { userErrors { field message } refund { id note totalRefundedSet { presentmentMoney { amount } } } } }",
 "variables": {
    "input": {
      "orderId": "gid://shopify/Order/734509473",
      "note": "Want to exchange for a different item",
      "refundLineItems": [
        {
          "lineItemId": "gid://shopify/LineItem/25746870",
          "quantity": 2
        }
      ],
      "transactions": [
        {
          "orderId": "gid://shopify/Order/734509473",
          "gateway": "foo",
          "kind": "REFUND",
          "amount": "10.0",
          "parentId": "gid://shopify/OrderTransaction/723599266"
        }
      ]
    }
  }
}'

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

const response = await admin.graphql(
  `#graphql
  mutation M($input: RefundInput!) {
    refundCreate(input: $input) {
      userErrors {
        field
        message
      }
      refund {
        id
        note
        totalRefundedSet {
          presentmentMoney {
            amount
          }
        }
      }
    }
  }`,
  {
    variables: {
      "input": {
        "orderId": "gid://shopify/Order/734509473",
        "note": "Want to exchange for a different item",
        "refundLineItems": [
          {
            "lineItemId": "gid://shopify/LineItem/25746870",
            "quantity": 2
          }
        ],
        "transactions": [
          {
            "orderId": "gid://shopify/Order/734509473",
            "gateway": "foo",
            "kind": "REFUND",
            "amount": "10.0",
            "parentId": "gid://shopify/OrderTransaction/723599266"
          }
        ]
      }
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation M($input: RefundInput!) {
      refundCreate(input: $input) {
        userErrors {
          field
          message
        }
        refund {
          id
          note
          totalRefundedSet {
            presentmentMoney {
              amount
            }
          }
        }
      }
    }`,
    "variables": {
      "input": {
        "orderId": "gid://shopify/Order/734509473",
        "note": "Want to exchange for a different item",
        "refundLineItems": [
          {
            "lineItemId": "gid://shopify/LineItem/25746870",
            "quantity": 2
          }
        ],
        "transactions": [
          {
            "orderId": "gid://shopify/Order/734509473",
            "gateway": "foo",
            "kind": "REFUND",
            "amount": "10.0",
            "parentId": "gid://shopify/OrderTransaction/723599266"
          }
        ]
      }
    },
  },
});

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
  mutation M($input: RefundInput!) {
    refundCreate(input: $input) {
      userErrors {
        field
        message
      }
      refund {
        id
        note
        totalRefundedSet {
          presentmentMoney {
            amount
          }
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "orderId": "gid://shopify/Order/734509473",
    "note": "Want to exchange for a different item",
    "refundLineItems": [{"lineItemId"=>"gid://shopify/LineItem/25746870", "quantity"=>2}],
    "transactions": [{"orderId"=>"gid://shopify/Order/734509473", "gateway"=>"foo", "kind"=>"REFUND", "amount"=>"10.0", "parentId"=>"gid://shopify/OrderTransaction/723599266"}]
  }
}

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

Input variables

JSON

{

"input": {

"orderId": "gid://shopify/Order/734509473",

"note": "Want to exchange for a different item",

"refundLineItems": [

{

"lineItemId": "gid://shopify/LineItem/25746870",

"quantity": 2

}

"transactions": [

{

"orderId": "gid://shopify/Order/734509473",

"gateway": "foo",

"kind": "REFUND",

"amount": "10.0",

"parentId": "gid://shopify/OrderTransaction/723599266"

}

]

}

Response

JSON

{

"refundCreate": {

"userErrors": [],

"refund": {

"id": "gid://shopify/Refund/929361479",

"note": "Want to exchange for a different item",

"totalRefundedSet": {

"presentmentMoney": {

"amount": "10.0"

}