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.

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.

Caution

As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive. As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive. For more information, see the idempotency documentation.

Anchor to Arguments

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?

Examples

Create a refund that's issued as a store credit

Description

Create a refund that's issued as store credit instead of returning it to the original payment method. The store credit amount is specified in the `refundMethods` field and applies to a specific line item in the order. The mutation returns the refund ID, total refunded amount, and transaction details associated with the store credit.

Query

mutation RefundToStoreCredit($input: RefundInput!) {
  refundCreate(input: $input) {
    userErrors {
      field
      message
    }
    refund {
      id
      totalRefundedSet {
        presentmentMoney {
          amount
          currencyCode
        }
      }
      transactions(first: 2) {
        edges {
          node {
            gateway
            kind
            amountSet {
              presentmentMoney {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
    order {
      id
    }
  }
}

Variables

{
  "input": {
    "orderId": "gid://shopify/Order/1073459983",
    "refundLineItems": [
      {
        "lineItemId": "gid://shopify/LineItem/1071823193",
        "quantity": 1
      }
    ],
    "transactions": [],
    "refundMethods": [
      {
        "storeCreditRefund": {
          "amount": {
            "amount": "10.00",
            "currencyCode": "USD"
          }
        }
      }
    ]
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation RefundToStoreCredit($input: RefundInput!) { refundCreate(input: $input) { userErrors { field message } refund { id totalRefundedSet { presentmentMoney { amount currencyCode } } transactions(first: 2) { edges { node { gateway kind amountSet { presentmentMoney { amount currencyCode } } } } } } order { id } } }",
 "variables": {
    "input": {
      "orderId": "gid://shopify/Order/1073459983",
      "refundLineItems": [
        {
          "lineItemId": "gid://shopify/LineItem/1071823193",
          "quantity": 1
        }
      ],
      "transactions": [],
      "refundMethods": [
        {
          "storeCreditRefund": {
            "amount": {
              "amount": "10.00",
              "currencyCode": "USD"
            }
          }
        }
      ]
    }
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation RefundToStoreCredit($input: RefundInput!) {
    refundCreate(input: $input) {
      userErrors {
        field
        message
      }
      refund {
        id
        totalRefundedSet {
          presentmentMoney {
            amount
            currencyCode
          }
        }
        transactions(first: 2) {
          edges {
            node {
              gateway
              kind
              amountSet {
                presentmentMoney {
                  amount
                  currencyCode
                }
              }
            }
          }
        }
      }
      order {
        id
      }
    }
  }`,
  {
    variables: {
        "input": {
            "orderId": "gid://shopify/Order/1073459983",
            "refundLineItems": [
                {
                    "lineItemId": "gid://shopify/LineItem/1071823193",
                    "quantity": 1
                }
            ],
            "transactions": [],
            "refundMethods": [
                {
                    "storeCreditRefund": {
                        "amount": {
                            "amount": "10.00",
                            "currencyCode": "USD"
                        }
                    }
                }
            ]
        }
    },
  },
  );
  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
  mutation RefundToStoreCredit($input: RefundInput!) {
    refundCreate(input: $input) {
      userErrors {
        field
        message
      }
      refund {
        id
        totalRefundedSet {
          presentmentMoney {
            amount
            currencyCode
          }
        }
        transactions(first: 2) {
          edges {
            node {
              gateway
              kind
              amountSet {
                presentmentMoney {
                  amount
                  currencyCode
                }
              }
            }
          }
        }
      }
      order {
        id
      }
    }
  }
QUERY

variables = {
  "input": {
    "orderId": "gid://shopify/Order/1073459983",
    "refundLineItems": [
      {
        "lineItemId": "gid://shopify/LineItem/1071823193",
        "quantity": 1
      }
    ],
    "transactions": [],
    "refundMethods": [
      {
        "storeCreditRefund": {
          "amount": {
            "amount": "10.00",
            "currencyCode": "USD"
          }
        }
      }
    ]
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation RefundToStoreCredit($input: RefundInput!) {
      refundCreate(input: $input) {
        userErrors {
          field
          message
        }
        refund {
          id
          totalRefundedSet {
            presentmentMoney {
              amount
              currencyCode
            }
          }
          transactions(first: 2) {
            edges {
              node {
                gateway
                kind
                amountSet {
                  presentmentMoney {
                    amount
                    currencyCode
                  }
                }
              }
            }
          }
        }
        order {
          id
        }
      }
    }`,
    "variables": {
        "input": {
            "orderId": "gid://shopify/Order/1073459983",
            "refundLineItems": [
                {
                    "lineItemId": "gid://shopify/LineItem/1071823193",
                    "quantity": 1
                }
            ],
            "transactions": [],
            "refundMethods": [
                {
                    "storeCreditRefund": {
                        "amount": {
                            "amount": "10.00",
                            "currencyCode": "USD"
                        }
                    }
                }
            ]
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation RefundToStoreCredit($input: RefundInput!) {
  refundCreate(input: $input) {
    userErrors {
      field
      message
    }
    refund {
      id
      totalRefundedSet {
        presentmentMoney {
          amount
          currencyCode
        }
      }
      transactions(first: 2) {
        edges {
          node {
            gateway
            kind
            amountSet {
              presentmentMoney {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
    order {
      id
    }
  }
}' \
--variables \
'{
  "input": {
    "orderId": "gid://shopify/Order/1073459983",
    "refundLineItems": [
      {
        "lineItemId": "gid://shopify/LineItem/1071823193",
        "quantity": 1
      }
    ],
    "transactions": [],
    "refundMethods": [
      {
        "storeCreditRefund": {
          "amount": {
            "amount": "10.00",
            "currencyCode": "USD"
          }
        }
      }
    ]
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2025-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation RefundToStoreCredit($input: RefundInput!) {
        refundCreate(input: $input) {
          userErrors {
            field
            message
          }
          refund {
            id
            totalRefundedSet {
              presentmentMoney {
                amount
                currencyCode
              }
            }
            transactions(first: 2) {
              edges {
                node {
                  gateway
                  kind
                  amountSet {
                    presentmentMoney {
                      amount
                      currencyCode
                    }
                  }
                }
              }
            }
          }
          order {
            id
          }
        }
      }
    `,
    variables: {
        "input": {
            "orderId": "gid://shopify/Order/1073459983",
            "refundLineItems": [
                {
                    "lineItemId": "gid://shopify/LineItem/1071823193",
                    "quantity": 1
                }
            ],
            "transactions": [],
            "refundMethods": [
                {
                    "storeCreditRefund": {
                        "amount": {
                            "amount": "10.00",
                            "currencyCode": "USD"
                        }
                    }
                }
            ]
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "refundCreate": {
    "userErrors": [],
    "refund": {
      "id": "gid://shopify/Refund/943333862",
      "totalRefundedSet": {
        "presentmentMoney": {
          "amount": "10.0",
          "currencyCode": "USD"
        }
      },
      "transactions": {
        "edges": [
          {
            "node": {
              "gateway": "shopify_store_credit",
              "kind": "REFUND",
              "amountSet": {
                "presentmentMoney": {
                  "amount": "10.0",
                  "currencyCode": "USD"
                }
              }
            }
          }
        ]
      }
    },
    "order": {
      "id": "gid://shopify/Order/1073459983"
    }
  }
}

refundCreate reference

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

mutation RefundToStoreCredit($input: RefundInput!) {

refundCreate(input: $input) {

userErrors {

field

message

}

refund {

totalRefundedSet {

presentmentMoney {

amount

currencyCode

}

transactions(first: 2) {

edges {

node {

gateway

kind

amountSet {

presentmentMoney {

amount

currencyCode

}

order {

}

}`,

{

variables: {

"input": {

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

"refundLineItems": [

{

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

"quantity": 1

}

"transactions": [],

"refundMethods": [

{

"storeCreditRefund": {

"amount": {

"amount": "10.00",

"currencyCode": "USD"

}

]

}

);

const json = await response.json();

return json.data;

}

GQL

mutation RefundToStoreCredit($input: RefundInput!) {
  refundCreate(input: $input) {
    userErrors {
      field
      message
    }
    refund {
      id
      totalRefundedSet {
        presentmentMoney {
          amount
          currencyCode
        }
      }
      transactions(first: 2) {
        edges {
          node {
            gateway
            kind
            amountSet {
              presentmentMoney {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
    order {
      id
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation RefundToStoreCredit($input: RefundInput!) { refundCreate(input: $input) { userErrors { field message } refund { id totalRefundedSet { presentmentMoney { amount currencyCode } } transactions(first: 2) { edges { node { gateway kind amountSet { presentmentMoney { amount currencyCode } } } } } } order { id } } }",
 "variables": {
    "input": {
      "orderId": "gid://shopify/Order/1073459983",
      "refundLineItems": [
        {
          "lineItemId": "gid://shopify/LineItem/1071823193",
          "quantity": 1
        }
      ],
      "transactions": [],
      "refundMethods": [
        {
          "storeCreditRefund": {
            "amount": {
              "amount": "10.00",
              "currencyCode": "USD"
            }
          }
        }
      ]
    }
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation RefundToStoreCredit($input: RefundInput!) {
    refundCreate(input: $input) {
      userErrors {
        field
        message
      }
      refund {
        id
        totalRefundedSet {
          presentmentMoney {
            amount
            currencyCode
          }
        }
        transactions(first: 2) {
          edges {
            node {
              gateway
              kind
              amountSet {
                presentmentMoney {
                  amount
                  currencyCode
                }
              }
            }
          }
        }
      }
      order {
        id
      }
    }
  }`,
  {
    variables: {
        "input": {
            "orderId": "gid://shopify/Order/1073459983",
            "refundLineItems": [
                {
                    "lineItemId": "gid://shopify/LineItem/1071823193",
                    "quantity": 1
                }
            ],
            "transactions": [],
            "refundMethods": [
                {
                    "storeCreditRefund": {
                        "amount": {
                            "amount": "10.00",
                            "currencyCode": "USD"
                        }
                    }
                }
            ]
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation RefundToStoreCredit($input: RefundInput!) {
      refundCreate(input: $input) {
        userErrors {
          field
          message
        }
        refund {
          id
          totalRefundedSet {
            presentmentMoney {
              amount
              currencyCode
            }
          }
          transactions(first: 2) {
            edges {
              node {
                gateway
                kind
                amountSet {
                  presentmentMoney {
                    amount
                    currencyCode
                  }
                }
              }
            }
          }
        }
        order {
          id
        }
      }
    }`,
    "variables": {
        "input": {
            "orderId": "gid://shopify/Order/1073459983",
            "refundLineItems": [
                {
                    "lineItemId": "gid://shopify/LineItem/1071823193",
                    "quantity": 1
                }
            ],
            "transactions": [],
            "refundMethods": [
                {
                    "storeCreditRefund": {
                        "amount": {
                            "amount": "10.00",
                            "currencyCode": "USD"
                        }
                    }
                }
            ]
        }
    },
  },
});

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
  mutation RefundToStoreCredit($input: RefundInput!) {
    refundCreate(input: $input) {
      userErrors {
        field
        message
      }
      refund {
        id
        totalRefundedSet {
          presentmentMoney {
            amount
            currencyCode
          }
        }
        transactions(first: 2) {
          edges {
            node {
              gateway
              kind
              amountSet {
                presentmentMoney {
                  amount
                  currencyCode
                }
              }
            }
          }
        }
      }
      order {
        id
      }
    }
  }
QUERY

variables = {
  "input": {
    "orderId": "gid://shopify/Order/1073459983",
    "refundLineItems": [
      {
        "lineItemId": "gid://shopify/LineItem/1071823193",
        "quantity": 1
      }
    ],
    "transactions": [],
    "refundMethods": [
      {
        "storeCreditRefund": {
          "amount": {
            "amount": "10.00",
            "currencyCode": "USD"
          }
        }
      }
    ]
  }
}

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

Shopify CLI

shopify app execute \
--query \
'mutation RefundToStoreCredit($input: RefundInput!) {
  refundCreate(input: $input) {
    userErrors {
      field
      message
    }
    refund {
      id
      totalRefundedSet {
        presentmentMoney {
          amount
          currencyCode
        }
      }
      transactions(first: 2) {
        edges {
          node {
            gateway
            kind
            amountSet {
              presentmentMoney {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
    order {
      id
    }
  }
}' \
--variables \
'{
  "input": {
    "orderId": "gid://shopify/Order/1073459983",
    "refundLineItems": [
      {
        "lineItemId": "gid://shopify/LineItem/1071823193",
        "quantity": 1
      }
    ],
    "transactions": [],
    "refundMethods": [
      {
        "storeCreditRefund": {
          "amount": {
            "amount": "10.00",
            "currencyCode": "USD"
          }
        }
      }
    ]
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2025-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation RefundToStoreCredit($input: RefundInput!) {
        refundCreate(input: $input) {
          userErrors {
            field
            message
          }
          refund {
            id
            totalRefundedSet {
              presentmentMoney {
                amount
                currencyCode
              }
            }
            transactions(first: 2) {
              edges {
                node {
                  gateway
                  kind
                  amountSet {
                    presentmentMoney {
                      amount
                      currencyCode
                    }
                  }
                }
              }
            }
          }
          order {
            id
          }
        }
      }
    `,
    variables: {
        "input": {
            "orderId": "gid://shopify/Order/1073459983",
            "refundLineItems": [
                {
                    "lineItemId": "gid://shopify/LineItem/1071823193",
                    "quantity": 1
                }
            ],
            "transactions": [],
            "refundMethods": [
                {
                    "storeCreditRefund": {
                        "amount": {
                            "amount": "10.00",
                            "currencyCode": "USD"
                        }
                    }
                }
            ]
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

"input": {

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

"refundLineItems": [

{

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

"quantity": 1

}

"transactions": [],

"refundMethods": [

{

"storeCreditRefund": {

"amount": {

"amount": "10.00",

"currencyCode": "USD"

}

]

}

Response

JSON

{

"refundCreate": {

"userErrors": [],

"refund": {

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

"totalRefundedSet": {

"presentmentMoney": {

"amount": "10.0",

"currencyCode": "USD"

}

"transactions": {

"edges": [

{

"node": {

"gateway": "shopify_store_credit",

"kind": "REFUND",

"amountSet": {

"presentmentMoney": {

"amount": "10.0",

"currencyCode": "USD"

}

]

}

"order": {

"id": "gid://shopify/Order/1073459983"

}