Refund duties with the GraphQL Admin API

API versions 2020-04 and higher

This guide explains how to use the GraphQL Admin API to preview and refund duties. To manage duties, you need to have a development store with the Duties and Taxes developer preview enabled.

Duties are calculated per line item, and can be viewed as a field of the LineItem object in the Admin API. Before refunding duties with the refundCreate mutation, you can preview the refund with the suggestedRefund query.

Refer to the GraphQL Admin API reference for more information on objects and mutations related to orders and refunds.

Access scopes

To use the GraphQL Admin API to refund duties, your app needs to request the write_order access scope for a Shopify store. For more information on requesting access scopes when your app is installed, see OAuth.

Creating an order with a duty charge

Before you can complete the tutorial, you need to create an international order with duties applied. You can create an international order with duties applied by using a developer preview store with the duties and taxes preview enabled.

Steps:

  1. Set a Harmonized System Code on all products that you expect to have duties applied.

  2. Make sure that your store has shipping rates set for all the countries that you plan to support.

  3. Make sure your development store is setup to place test orders.

  4. Complete a checkout from your storefront. For the shipping address step, you need to enter a different country than where your product is being fulfilled from. If duties apply to your order, then they are displayed on the shipping rates view and order summary.

  1. On the order details page of your Shopify admin, verify that duties have been charged on the order.

Retrieve duties applied to an order

When you query an order, you can retrieve the total duties applied using the currentTotalDutiesSet field. If you want to retrieve the duties applied to each line item, then you can include the duties field on the lineItems connection.