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:
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 your development store is setup to place test orders.
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.
- 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.
Preview and refund an order including duties
You can preview a refund using the suggestedRefund query and then use the refundCreate mutation when you’re ready to create the refund.
Both suggestedRefund and refundCreate use the input type RefundDutyInput, which requires a dutyId and a refundType that specifies how you would like the duty refunded. The two supported refund types are proportional and full.
The proportional refund type refunds duties in proportion to the line item quantity that you want to refund. If you choose the proportional refund type, then you must also pass the refund line items to calculate the portion of duties to refund.
The full refund type refunds all the duties associated with a duty ID. You do not need to include refund line items if you are using the full refund type.
Preview a proportional duty refund
In the suggestedRefund query, include the the duty ID, the refund type, and the ID and quantity of the line items that you want to preview the refund for.
Preview a full duty refund
You do not need to include an order's line items when you preview a full refund type.
Create a refund including duties
When you’re ready to create a refund, include the the following input parameters in the refundCreate mutation:
- The order ID.
- The ID and quantity of the line items that you want to refund.
- The duty ID.
- The refund type.
Additional information
For additional information on orders refer to the GraphQL Admin API reference.