View and refund duties

Customers might be charged additional duties when they receive international shipments. If a customer requests a refund on an international order, then you can refund duties that were previously applied to the order.

This guide shows you how to preview and refund duties with the GraphQL Admin API.

Requirements

Anchor link to section titled "Requirements"

Your app can make authenticated requests to the GraphQL Admin API.
Your app has the write_orders access scope. Learn how to configure your access scopes using Shopify CLI.
You have a development store with the Shopify Markets developer preview enabled so that you can manage duties.
You've met Shopify's protected customer data requirements.

Step 1: Create an order with a duty charge

Anchor link to section titled "Step 1: Create an order with a duty charge"

To preview and refund duties, you first need to create an international order with duties applied. You can create an international order with duties applied by using a development store that has the Shopify Markets developer preview enabled.

Set a Harmonized System Code on all products that you expect to have duties applied.
Make sure that your store has shipping rates set for all the countries that you plan to support.
Make sure that your development store is set up to place test orders.
Complete a checkout from your storefront.

For the shipping information checkout step, you need to enter a different country than the location where your product is fulfilled. If duties apply to your order, then they're displayed on the shipping rates view and order summary.

Note

Duties might not be applied if the price of the order doesn't exceed the destination country’s de minimis threshold.
On the order details page of your Shopify admin, verify that duties have been charged on the order.

Duties are calculated for each line item, and can be viewed in the duties field on the LineItem object in the GraphQL Admin API.

Step 2: Retrieve duties on an order

Anchor link to section titled "Step 2: Retrieve duties on an order"

When you query an order, you can retrieve the total duties that are 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 LineItem field on the lineItems connection.

Step 3: Preview a refund that includes duties

Anchor link to section titled "Step 3: Preview a refund that includes duties"

Before refunding duties, you can preview the refund using the suggestedRefund query. You can then use the refundCreate mutation when you’re ready to create the refund.

The supported refund types are PROPORTIONAL and FULL.

Preview a proportional duty refund

Anchor link to section titled "Preview a proportional duty refund"

The PROPORTIONAL refund type refunds duties in proportion to the line item quantity that you want to refund.

In the suggestedRefund query, include the duty ID, the refund type, and the ID and quantity of the line items that you want to preview the refund for. You must pass the refund line items to calculate the portion of duties to refund.

Preview a full duty refund

Anchor link to section titled "Preview a full duty refund"

The FULL refund type refunds all the duties associated with a duty ID. In the suggestedRefund query, you don't need to include an order's line items when you preview a FULL refund type.

Step 4: Create a refund that includes duties

Anchor link to section titled "Step 4: Create a refund that includes duties"

When you’re ready to create a refund, you can use the refundCreate mutation. Include the order ID, the ID and quantity of the line items that you want to refund, the duty ID, and the refund type as input to the mutation.

Next steps

Anchor link to section titled "Next steps"

Learn how to manage reverse fulfillment orders with the GraphQL Admin API.
Learn how to manage reverse deliveries with the GraphQL Admin API.