Version 2019-10


Apps are required to specify a restock_type and a location_id on the refund_line_item. For more information, see Migrating to multi-location inventory.

There are two major parts to a refund:

Before you create a refund, use the calculate endpoint to generate accurate refund transactions. Specify the line items that are being refunded, their quantity and restock instructions, and whether you're refunding shipping costs. You can then use the response in the body of the request to create the actual refund.

When you create a refund using the response from the calculate endpoint, you can set additional options, such as whether to notify the customer of the refund. You can refund less than the calculated amount for either shipping or the line items by setting a custom value for the amount property.

If a refund includes shipping costs, or if you choose to refund line items for less than their calculated amount, then an order adjustment is created automatically to account for the discrepancy in the store's financial reports.

What you can do with Refund

The Shopify API lets you do the following with the Refund resource. More detailed versions of these general actions may be available:

Refund properties

"created_at": "2008-01-10T11:00:00-05:00"

The date and time (ISO 8601 format) when the refund was created.

"id": 92738740

The unique identifier for the refund.

"note": "Item was damaged during shipping"

An optional note attached to a refund.

"order_adjustments": [
    "id": 4221763620,
    "order_id": 171016912932,
    "refund_id": 8244756516,
    "amount": "-8.00",
    "tax_amount": "0.00",
    "kind": "shipping_refund",
    "reason": "Shipping refund",
    "amount_set": {
      "shop_money": {
        "amount": 10.99,
        "currency_code": "USD"
      "presentment_money": {
        "amount": 12.95,
        "currency_code": "CAD"
    "tax_amount_set": {
      "shop_money": {
        "amount": 1.67,
        "currency_code": "USD"
      "presentment_money": {
        "amount": 2.32,
        "currency_code": "CAD"

A list of order adjustments attached to the refund. Order adjustments are generated to account for refunded shipping costs and differences between calculated and actual refund amounts. Each entry has the following properties:

  • id: The unique identifier for the order adjustment.
  • order_id: The unique identifier for the order that the order adjustment is associated with.
  • refund_id: The unique identifier for the refund that the order adjustment is associated with.
  • amount: The value of the discrepancy between the calculated refund and the actual refund. If the kind property's value is shipping_refund, then amount returns the value of shipping charges refunded to the customer.
  • tax_amount: The taxes that are added to amount, such as applicable shipping taxes added to a shipping refund.
  • kind: The order adjustment type. Valid values: shipping_refund and refund_discrepancy.
  • reason: The reason for the order adjustment. To set this value, include discrepancy_reason when you create a refund.
  • amount_set: The amount of the order adjustment in shop and presentment currencies.
  • tax_amount_set: The tax amount of the order adjustment in shop and presentment currencies.

"processed_at": "2007-01-10T11:00:00-05:00"

The date and time (ISO 8601 format) when the refund was imported. This value can be set to a date in the past when importing from other systems. If no value is provided, then it will be auto-generated as the current time in Shopify.

"refund_line_items": [
    "id": 209341123,
    "line_item": {},
    "line_item_id": 128323456,
    "quantity": 2,
    "location_id": 40642626,
    "restock_type": "return",
    "subtotal": 10.99,
    "total_tax": 2.67,
    "subtotal_set": {
      "shop_money": {
        "amount": 10.99,
        "currency_code": "CAD"
      "presentment_money": {
        "amount": 8.95,