Refund a Shopify order

Purpose

Refund a specified Shopify order, confirming the recipient/customer and order contents before submitting the refund. Complete any required account verification, MFA, hCaptcha, password-authentication, and authorization prerequisites.

When to Use

Use for Shopify admin refund requests when the order is identified by a product, customer, or order number and the account may require email verification, password authentication, SMS MFA, hCaptcha, or authorization for the write_orders scope.

Workflow

1. If the opaque Shopify order ID is already known, navigate directly to https://admin.shopify.com/store/{store-handle}/orders/{order-id}. Otherwise, open the Shopify admin Orders area and search for {product-or-order-query} and {customer-name}; select the matching order and read its numeric order ID from the resulting URL.
2. If redirected to Shopify account verification, solve the hCaptcha when presented, enter {account-email} in input#account_email, and submit with button[name='commit']. Wait for the verification response; solve a second hCaptcha and submit again if presented. Verification URLs under /lookup?rid=...&verify=... are short-lived and must not be reused.
3. If Shopify presents the login page and the preferred method is unavailable, use the current request's rid only to navigate to https://accounts.shopify.com/login/alternatives?rid={current-rid}, then choose password authentication or navigate to https://accounts.shopify.com/login?auth_method=password_auth&rid={current-rid}. Enter the user-supplied password in input#account_password and submit with button[name='commit']; never save, log, or hardcode the password.
4. If the existing session reaches an SMS MFA page, use the current page or its current-session URL and enter the user-supplied six-digit code in input#account_tfa_code, then submit with button[name='commit']. Do not retain, log, or hardcode the code. If an authorization or consent gate requests write_orders, approve that scope only when it is explicitly required for the requested refund, then continue to the admin session.
5. On the order page, run this evaluator to confirm the order identity and visible contents before taking action:

(() => {
  const root = document.querySelector("main") || document.body;
  const text = (root.innerText || "").replace(/\u00a0/g, " ").trim();
  const lines = text
    .split(/\n+/)
    .map((s) => s.trim())
    .filter(Boolean);
  const orderId = (location.pathname.match(/\/orders\/(\d+)/) || [])[1] || null;
  const customerLabelIndex = lines.findIndex((line) =>
    /customer|contact|shipping address|billing address/i.test(line),
  );
  const customer =
    customerLabelIndex >= 0 ? lines[customerLabelIndex + 1] || null : null;
  const items = lines.filter((line) =>
    /quantity|sku|variant|product|item/i.test(line),
  );
  return { orderId, customer, items, pageText: text };
})();

6. Confirm the extracted order belongs to {customer-name} and contains the requested product or order details. Use the order page's Refund action, select the applicable items/quantities and refund amount, and submit the refund. Report the resulting refund confirmation and amount.

Site-Specific Gotchas

• Shopify admin order URLs use the durable pattern /store/{store-handle}/orders/{numeric-order-id}; the numeric ID is opaque and must be resolved from an order result rather than guessed.
• Account verification may require hCaptcha both before and after submitting the account email. Allow each challenge to finish before submitting again.
• When the normal login method is unavailable, Shopify exposes /login/alternatives?rid={current-rid} and a password-auth route using the same current-session rid; do not invent or persist the rid.
• An existing login session can require SMS MFA at /login/two-factor/sms/{challenge-id}?rid={request-id}. The challenge ID and rid are session-specific; use the currently supplied/current-session URL rather than fabricating or persisting either value.
• The SMS code field is input#account_tfa_code and the submit control is button[name='commit']; treat the supplied code as sensitive and never put it in a saved recipe.
• Password authentication uses input#account_password and button[name='commit']; credentials are user-supplied secrets and must not be retained.
• /lookup verification URLs contain expiring rid and verify parameters; do not save or construct them for later runs.
• If a Shopify authorization gate explicitly requests write_orders, grant that required scope before attempting the refund; do not broaden authorization beyond the requested scope.
• The evaluator intentionally reads only the loaded order page. Its main/body-text fallback is less stable than dedicated Shopify selectors, so visually or textually verify the customer and product before refunding.
• Do not submit a refund until both the customer and the intended line item are confirmed; similarly named orders can coexist.

Expected Output

Return the Shopify order ID, matched customer, refunded line item(s), refund amount, and Shopify's confirmation status or reference. Indicate whether required MFA, password authentication, hCaptcha, and write_orders authorization were completed, without revealing MFA codes, passwords, or credentials.