Preview 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.
RequirementsAnchor link to section titled "Requirements"
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_ordersaccess scope. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
- 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 chargeAnchor 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.
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
dutiesfield on the
LineItemobject in the GraphQL Admin API.
Step 2: Retrieve duties on an orderAnchor 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
Step 3: Preview a refund that includes dutiesAnchor 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
Preview a proportional duty refundAnchor link to section titled "Preview a proportional duty refund"
PROPORTIONAL refund type refunds duties in proportion to the line item quantity that you want to refund.
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 refundAnchor link to section titled "Preview a full duty refund"
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 dutiesAnchor 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.
- Learn how to manage reverse fulfillment orders with the GraphQL Admin API.
- Learn how to manage reverse deliveries with the GraphQL Admin API.