All Tutorials

Refund duties with the GraphQL Admin API

All Tutorials

Refund duties with the GraphQL Admin API

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.

Query

{
  order(id: "gid://shopify/Order/3") {
    currentTotalDutiesSet {
      shopMoney {
        amount
      }
    }
    lineItems(first: 10) {
      edges {
        node {
          id
          refundableQuantity
          duties {
            id
            harmonizedSystemCode
            price {
              shopMoney {
                amount
              }
            }
          }
        }
      }
    }
  }
}

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"
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}

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.

Query

query suggestedRefund {
  order(id: "gid://shopify/Order/3") {
    suggestedRefund(refundLineItems: [{lineItemId:"gid://shopify/LineItem/2", quantity: 1}], refundDuties: [{ dutyId: "gid://shopify/Duty/1", refundType: PROPORTIONAL}]) {
      refundDuties {
        amountSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        originalDuty {
          id
        }
      }
      totalDutiesSet {
        shopMoney {
          amount
          currencyCode
        }
      }
    }
  }
}

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"
          }
        }
      }
    }
  }
}

Preview a full duty refund

You do not need to include an order's line items when you preview a full refund type.

query suggestedRefund {
  order(id: "gid://shopify/Order/3") {
    suggestedRefund(
      refundDuties: [{ dutyId: "gid://shopify/Duty/1", refundType: FULL }]
    ) {
      refundDuties {
        amountSet {
          shopMoney {
            amount
            currencyCode
          }
        }
      }
      totalDutiesSet {
        shopMoney {
          amount
          currencyCode
        }
      }
    }
  }
}

Response

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

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.

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
          }
        }
      }
    }
  }
}

Response

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

Additional information

For additional information on orders refer to the GraphQL Admin API reference.