Skip to main content

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.

Developer preview

The functionality to refund duties is in the Shopify Markets developer preview. The values that are returned are generated and aren't consistent with actual duty rates set by each country.

Anchor to RequirementsRequirements

Anchor to Step 1: Create an order with a duty chargeStep 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.

  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 that your development store is set up to place test orders.

  4. 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.

  5. 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.

Anchor to Step 2: Retrieve duties on an orderStep 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.

Tip

You can retrieve an order's ID with the orders query.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
# The ID of the order.
order(id: "gid://shopify/Order/3") {
# The total amount of duties after returns, in shop and presentment currencies. Returns `null` if duties aren't applicable.
currentTotalDutiesSet {
shopMoney {
amount
}
}
lineItems(first: 10) {
edges {
node {
id
refundableQuantity
# The duties associated with the line item.
duties {
id
harmonizedSystemCode
price {
shopMoney {
amount
}
}
}
}
}
}
}
}

JSON response

{
"data": {
"order": {
"currentTotalDutiesSet": {
"shopMoney": {
"amount": "668.19"
}
},
"lineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/LineItem/2",
"refundableQuantity": 5,
"duties": [
{
"id": "gid://shopify/Duty/1",
"harmonizedSystemCode": "520100",
"price": {
"shopMoney": {
"amount": "668.19"
}
}
}
]
}
}
]
}
}
}
}

Anchor to Step 3: Preview a refund that includes dutiesStep 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.

Anchor to Preview a proportional duty refundPreview 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query suggestedRefund {
order(id: "gid://shopify/Order/3") {
suggestedRefund(refundLineItems: [{lineItemId:"gid://shopify/LineItem/2", quantity: 1}],
# The `suggestedRefund` query uses the input type `RefundDutyInput`, which requires a `dutyId` and a `refundType` that specifies how you want the duty refunded.
refundDuties: [{ dutyId: "gid://shopify/Duty/1", refundType: PROPORTIONAL}]) {
refundDuties {
amountSet {
shopMoney {
amount
currencyCode
}
}
originalDuty {
id
}
}
totalDutiesSet {
shopMoney {
amount
currencyCode
}
}
}
}
}

JSON response

{
"data": {
"order": {
"suggestedRefund": {
"refundDuties": [
{
"amountSet": {
"shopMoney": {
"amount": "133.65",
"currencyCode": "CAD"
}
},
"originalDuty": {
"id": "gid://shopify/Duty/1"
}
}
],
"totalDutiesSet": {
"shopMoney": {
"amount": "133.65",
"currencyCode": "CAD"
}
}
}
}
}
}

Anchor to Preview a full duty refundPreview 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query suggestedRefund {
order(id: "gid://shopify/Order/3") {
suggestedRefund(
# The `suggestedRefund` query uses the input type `RefundDutyInput`, which requires a `dutyId` and a `refundType` that specifies how you want the duty refunded.
refundDuties: [{ dutyId: "gid://shopify/Duty/1", refundType: FULL }]
) {
refundDuties {
amountSet {
shopMoney {
amount
currencyCode
}
}
}
totalDutiesSet {
shopMoney {
amount
currencyCode
}
}
}
}
}

JSON response

{
"data": {
"order": {
"suggestedRefund": {
"refundDuties": [
{
"amountSet": {
"shopMoney": {
"amount": "668.19",
"currencyCode": "CAD"
}
}
}
],
"totalDutiesSet": {
"shopMoney": {
"amount": "668.19",
"currencyCode": "CAD"
}
}
}
}
}
}

Anchor to Step 4: Create a refund that includes dutiesStep 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation refundIncludingDuties {
refundCreate(input:{orderId:"gid://shopify/Order/3", refundLineItems: [{lineItemId:"gid://shopify/LineItem/2", quantity: 1}], refundDuties: [{dutyId: "gid://shopify/Duty/1", refundType: PROPORTIONAL}] }) {
refund {
duties {
originalDuty {
id
}
amountSet {
shopMoney {
amount
}
}
}
}
}
}

JSON response

{
"data": {
"refundCreate": {
"refund": {
"duties": [
{
"originalDuty": {
"id": "gid://shopify/Duty/1"
},
"amountSet": {
"shopMoney": {
"amount": "133.65"
}
}
}
]
}
},
"userErrors": []
}
}

Anchor to Next stepsNext steps

Was this page helpful?