How to refund tax

GraphQL Admin API Troubleshooting
1

I would appreciate guidance on the correct way to handle taxes when issuing refunds/partial refunds using the Admin GraphQL API.

My use case is the following:

  • A customer places an order with taxable products.

  • When issuing a refund, I need to apply a deduction (for example an admin or restocking fee).

  • I want to ensure that tax is refunded correctly and in compliance with Shopify’s tax logic.

More specifically, I would like clarification on:

  1. Whether tax is calculated and refunded automatically by Shopify when refunding line items using refundCreate (GraphQL), based only on lineItemId and quantity.

  2. How deductions (such as admin fees) should be applied:

    • Should they be handled using refundAdjustments within refundCreate?

    • Or is there another recommended approach?

  3. Whether tax calculations and refunds are handled at the line item (product) level or at the order level.

  4. In a scenario where part of the product value is not refunded due to a deduction, how Shopify determines the correct tax amount to refund.

Example scenario:

  • Product price: $100

  • Tax: 10% ($10)

  • Deduction/admin fee: $20

  • Refunded product value: $80

In this case, I want to confirm the correct way to structure the refundCreate mutation so that Shopify automatically refunds the correct portion of tax, without me manually calculating or supplying tax values in my own system.

Any best practices or example workflows for this scenario would be very helpful.

Thank you in advance for your guidance.

Best regards,
Johanna

2

Hey @Johanna_Meless! When you pass a lineItemId and quantity in refundLineItems, Shopify calculates the proportional tax refund for you.

The recommended approach is two steps. First, query suggestedRefund on the order to preview amounts:

query PreviewRefund {
  order(id: "gid://shopify/Order/YOUR_ORDER_ID") {
    suggestedRefund(
      refundLineItems: [
        { lineItemId: "gid://shopify/LineItem/YOUR_LINE_ITEM_ID", quantity: 1 }
      ]
    ) {
      amountSet { shopMoney { amount currencyCode } }
      subtotalSet { shopMoney { amount currencyCode } }
      totalTaxSet { shopMoney { amount currencyCode } }
      suggestedTransactions { amountSet { shopMoney { amount currencyCode } } parentTransaction { id } gateway kind }
    }
  }
}

For your $100 + $10 tax example, this would return $100 subtotal, $10 tax, $110 total, plus suggestedTransactions with the parentId and gateway you’ll need for step two.

For the deduction, there’s no refundAdjustments field on RefundInput. Instead, you reduce the amount in transactions when calling refundCreate and set discrepancyReason to explain the difference:

{
  "input": {
    "orderId": "gid://shopify/Order/YOUR_ORDER_ID",
    "refundLineItems": [
      { "lineItemId": "gid://shopify/LineItem/YOUR_LINE_ITEM_ID", "quantity": 1 }
    ],
    "discrepancyReason": "OTHER",
    "transactions": [
      {
        "orderId": "gid://shopify/Order/YOUR_ORDER_ID",
        "parentId": "gid://shopify/OrderTransaction/PARENT_TXN_ID",
        "kind": "REFUND",
        "gateway": "YOUR_GATEWAY",
        "amount": "90.00"
      }
    ]
  }
}

I hope this helps, let me know if you have any questions about the above!