Refund

Version 2019-10

Important

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
read-only 
"created_at": "2008-01-10T11:00:00-05:00"

The date and time (ISO 8601 format) when the refund was created.
id
read-only 
"id": 92738740

The unique identifier for the refund.
note 
"note": "Item was damaged during shipping"

An optional note attached to a refund.
order_adjustments
read-only 
"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 
"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 
"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,
        "currency_code": "USD"
      }
    },
    "total_tax_set": {
      "shop_money": {
        "amount": 1.67,
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": 1.32,
        "currency_code": "USD"
      }
    }
  }
]

A list of refunded line items. Each entry has the following properties:

  • id: The unique identifier of the line item in the refund.
  • line_item: A line item being returned.
  • line_item_id: The ID of the related line item in the order.
  • quantity: The quantity of the associated line item that was returned.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory. The number of fulfillable units for this line item will remain unchanged. For example, a refund payment can be issued but no items will be returned or made available for sale again.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered, and will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
    • legacy_restock: The deprecated restock property was used for this refund. These items were made available for sale again. This value is not accepted when creating new refunds.
  • location_id: The unique identifier of the location where the items will be restocked. Required when restock_type has the value return or cancel.
  • subtotal: The subtotal of the refund line item.
  • total_tax: The total tax on the refund line item.
  • subtotal_set: The subtotal of the refund line item in shop and presentment currencies.
  • total_tax_set: The total tax of the line item in shop and presentment currencies.
restock
deprecated 
"restock": true

Whether to add the line items back to the store's inventory.

Provide a restock_type to influence how this refund affects inventory instead
transactions 
"transactions": [
  {
    "id": 179259969,
    "order_id": 450789469,
    "amount": "209.00",
    "kind": "refund",
    "gateway": "shopify_payments",
    "status": "success",
    "message": null,
    "created_at": "2005-08-05T12:59:12-04:00",
    "test": false,
    "authorization": "authorization-key",
    "currency": "USD",
    "location_id": null,
    "user_id": null,
    "parent_id": 801038806,
    "device_id": null,
    "receipt": {},
    "error_code": null,
    "source_name": "web"
  }
]

A list of transactions involved in the refund. For more information, see the Transaction resource.
user_id 
"user_id": 238478920

The unique identifier of the user who performed the refund.

Endpoints

GET /admin/api/2019-10/orders/{order_id}/refunds.json
Retrieves a list of refunds for an order. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency

Show amounts in the shop currency for the underlying transaction.

(default: false)

Retrieve all refunds from a specific order

GET /admin/api/2020-07/orders/450789469/refunds.json
View Response 
HTTP/1.1 200 OK
{
  "refunds": [
    {
      "id": 509562969,
      "order_id": 450789469,
      "created_at": "2020-09-08T13:05:54-04:00",
      "note": "it broke during shipping",
      "user_id": 799407056,
      "processed_at": "2020-09-08T13:05:54-04:00",
      "restock": true,
      "duties": [],
      "admin_graphql_api_id": "gid://shopify/Refund/509562969",
      "refund_line_items": [
        {
          "id": 104689539,
          "quantity": 1,
          "line_item_id": 703073504,
          "location_id": 487838322,
          "restock_type": "legacy_restock",
          "subtotal": 195.67,
          "total_tax": 3.98,
          "subtotal_set": {
            "shop_money": {
              "amount": "195.67",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "195.67",
              "currency_code": "USD"
            }
          },
          "total_tax_set": {
            "shop_money": {
              "amount": "3.98",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "3.98",
              "currency_code": "USD"
            }
          },
          "line_item": {
            "id": 703073504,
            "variant_id": 457924702,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "sku": "IPOD2008BLACK",
            "variant_title": "black",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - black",
            "variant_inventory_management": "shopify",
            "properties": [],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "price": "199.00",
            "total_discount": "0.00",
            "fulfillment_status": null,
            "price_set": {
              "shop_money": {
                "amount": "199.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "199.00",
                "currency_code": "USD"
              }
            },
            "total_discount_set": {
              "shop_money": {
                "amount": "0.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "0.00",
                "currency_code": "USD"
              }
            },
            "discount_allocations": [
              {
                "amount": "3.33",
                "discount_application_index": 0,
                "amount_set": {
                  "shop_money": {
                    "amount": "3.33",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.33",
                    "currency_code": "USD"
                  }
                }
              }
            ],
            "duties": [],
            "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06,
                "price_set": {
                  "shop_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  }
                }
              }
            ]
          }
        },
        {
          "id": 709875399,
          "quantity": 1,
          "line_item_id": 466157049,
          "location_id": 487838322,
          "restock_type": "legacy_restock",
          "subtotal": 195.66,
          "total_tax": 3.98,
          "subtotal_set": {
            "shop_money": {
              "amount": "195.66",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "195.66",
              "currency_code": "USD"
            }
          },
          "total_tax_set": {
            "shop_money": {
              "amount": "3.98",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "3.98",
              "currency_code": "USD"
            }
          },
          "line_item": {
            "id": 466157049,
            "variant_id": 39072856,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "sku": "IPOD2008GREEN",
            "variant_title": "green",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - green",
            "variant_inventory_management": "shopify",
            "properties": [
              {
                "name": "Custom Engraving Front",
                "value": "Happy Birthday"
              },
              {
                "name": "Custom Engraving Back",
                "value": "Merry Christmas"
              }
            ],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "price": "199.00",
            "total_discount": "0.00",
            "fulfillment_status": null,
            "price_set": {
              "shop_money": {
                "amount": "199.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "199.00",
                "currency_code": "USD"
              }
            },
            "total_discount_set": {
              "shop_money": {
                "amount": "0.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "0.00",
                "currency_code": "USD"
              }
            },
            "discount_allocations": [
              {
                "amount": "3.34",
                "discount_application_index": 0,
                "amount_set": {
                  "shop_money": {
                    "amount": "3.34",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.34",
                    "currency_code": "USD"
                  }
                }
              }
            ],
            "duties": [],
            "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06,
                "price_set": {
                  "shop_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  }
                }
              }
            ]
          }
        }
      ],
      "transactions": [
        {
          "id": 179259969,
          "order_id": 450789469,
          "kind": "refund",
          "gateway": "bogus",
          "status": "success",
          "message": null,
          "created_at": "2005-08-05T12:59:12-04:00",
          "test": false,
          "authorization": "authorization-key",
          "location_id": null,
          "user_id": null,
          "parent_id": 801038806,
          "processed_at": "2005-08-05T12:59:12-04:00",
          "device_id": null,
          "receipt": {},
          "error_code": null,
          "source_name": "web",
          "currency_exchange_adjustment": null,
          "amount": "209.00",
          "currency": "USD",
          "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
        }
      ],
      "order_adjustments": []
    }
  ]
}
GET /admin/api/2019-10/orders/{order_id}/refunds/{refund_id}.json
Retrieves a specific refund.
fields

Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency

Show amounts in the shop currency for the underlying transaction.

(default: false)

Retrieve a specific refund

GET /admin/api/2020-07/orders/450789469/refunds/509562969.json
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "id": 509562969,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:05:54-04:00",
    "note": "it broke during shipping",
    "user_id": 799407056,
    "processed_at": "2020-09-08T13:05:54-04:00",
    "restock": true,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/509562969",
    "refund_line_items": [
      {
        "id": 104689539,
        "quantity": 1,
        "line_item_id": 703073504,
        "location_id": 487838322,
        "restock_type": "legacy_restock",
        "subtotal": 195.67,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.67",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.67",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 703073504,
          "variant_id": 457924702,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008BLACK",
          "variant_title": "black",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - black",
          "variant_inventory_management": "shopify",
          "properties": [],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.33",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      },
      {
        "id": 709875399,
        "quantity": 1,
        "line_item_id": 466157049,
        "location_id": 487838322,
        "restock_type": "legacy_restock",
        "subtotal": 195.66,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.66",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.66",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 466157049,
          "variant_id": 39072856,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008GREEN",
          "variant_title": "green",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - green",
          "variant_inventory_management": "shopify",
          "properties": [
            {
              "name": "Custom Engraving Front",
              "value": "Happy Birthday"
            },
            {
              "name": "Custom Engraving Back",
              "value": "Merry Christmas"
            }
          ],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.34",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 179259969,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": null,
        "created_at": "2005-08-05T12:59:12-04:00",
        "test": false,
        "authorization": "authorization-key",
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2005-08-05T12:59:12-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "web",
        "currency_exchange_adjustment": null,
        "amount": "209.00",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
      }
    ],
    "order_adjustments": []
  }
}
POST /admin/api/2019-10/orders/{order_id}/refunds/calculate.json

Calculates refund transactions based on line items and shipping. When you want to create a refund, you should first 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 intend to refund shipping costs. If the restock instructions can't be met—for example, because you try to return more items than have been fulfilled—then the endpoint returns modified restock instructions. You can then use the response in the body of the request to create the actual refund.

The response includes a transactions object with "kind": "suggested_refund", which must to be changed to "kind" : "refund" for the refund to be accepted.

shipping

Specify how much shipping to refund. It has the following properties:

  • full_refund: Whether to refund all remaining shipping.
  • amount: Set a specific amount to refund for shipping. Takes precedence over full_refund.
refund_line_items

A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:

  • line_item_id: The ID of a line item to refund.
  • quantity: The quantity to refund.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered but will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
  • location_id: The ID of the location where the items should be restocked. If location_id is not provided and the value of restock_type is return or cancel, then the endpoint returns a suitable location ID.
  • already_stocked: Whether the item is already stocked at the location. If this is false, then creating the refund will connect the item to the location and start stocking it there.
currency

The three-letter code (ISO 4217 format) for the currency used for the refund. Note: Required whenever the shipping amount property is provided.

Calculate the refund without specifying currency

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "no_restock"
      }
    ]
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "5.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [
      {
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": null,
        "restock_type": "no_restock",
        "price": "199.00",
        "subtotal": "195.67",
        "total_tax": "3.98",
        "discounted_price": "199.00",
        "discounted_total_price": "199.00",
        "total_cart_discount_amount": "3.33"
      }
    ],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "41.94",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}

Calculate the refund for a line item and shipping

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "no_restock"
      }
    ]
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "5.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [
      {
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": null,
        "restock_type": "no_restock",
        "price": "199.00",
        "subtotal": "195.67",
        "total_tax": "3.98",
        "discounted_price": "199.00",
        "discounted_total_price": "199.00",
        "total_cart_discount_amount": "3.33"
      }
    ],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "41.94",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}

Calculate a refund for a partial amount of shipping

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "amount": 2.0
    }
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "2.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "2.00",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}
POST /admin/api/2019-10/orders/{order_id}/refunds.json

Creates a refund. Use the calculate endpoint to produce the transactions to submit.


restock
deprecated

Whether to add the line items back to the store inventory. Use restock_type for refund line items instead.
notify

Whether to send a refund notification to the customer.
note

An optional note attached to a refund.
discrepancy_reason

An optional comment that explains a discrepancy between calculated and actual refund amounts. Used to populate the reason property of the resulting order adjustment object attached to the refund. Valid values: restock, damage, customer, and other.
shipping

Specify how much shipping to refund. It has the following properties:

  • full_refund: Whether to refund all remaining shipping.
  • amount: Set a specific amount to refund for shipping. Takes precedence over full_refund.
refund_line_items

A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:

  • line_item_id: The ID of a line item to refund.
  • quantity: The quantity to refund.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered but will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
  • location_id: The ID of the location where the items should be restocked. This is required when the value of restock_type is return or cancel. If the item is not already stocked at the location, then the item is connected to the location. An error is returned when the item is connected to a fulfillment service location and a different location is provided.
transactions

A list of transactions to process as refunds.

currency

The three-letter code (ISO 4217 format) for the currency used for the refund.

Create a refund for an order

POST /admin/api/2020-07/orders/450789469/refunds.json
{
  "refund": {
    "currency": "USD",
    "notify": true,
    "note": "wrong size",
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "return",
        "location_id": 487838322
      }
    ],
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 41.94,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
View Response 
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361465,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:24:21-04:00",
    "note": "wrong size",
    "user_id": null,
    "processed_at": "2020-09-08T13:24:21-04:00",
    "restock": true,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/929361465",
    "refund_line_items": [
      {
        "id": 1058498312,
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": 487838322,
        "restock_type": "return",
        "subtotal": 195.67,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.67",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.67",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 518995019,
          "variant_id": 49148385,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008RED",
          "variant_title": "red",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - red",
          "variant_inventory_management": "shopify",
          "properties": [],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.33",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/518995019",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 1072844691,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2020-09-08T13:24:21-04:00",
        "test": true,
        "authorization": null,
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2020-09-08T13:24:21-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713",
        "currency_exchange_adjustment": null,
        "amount": "41.94",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844691"
      }
    ],
    "order_adjustments": []
  }
}

Refund a specific amount of shipping

POST /admin/api/2020-07/orders/450789469/refunds.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "amount": 5.0
    },
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 5.0,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
View Response 
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361466,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:24:23-04:00",
    "note": null,
    "user_id": null,
    "processed_at": "2020-09-08T13:24:23-04:00",
    "restock": false,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/929361466",
    "refund_line_items": [],
    "transactions": [
      {
        "id": 1072844692,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2020-09-08T13:24:23-04:00",
        "test": true,
        "authorization": null,
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2020-09-08T13:24:23-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713",
        "currency_exchange_adjustment": null,
        "amount": "5.00",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844692"
      }
    ],
    "order_adjustments": [
      {
        "id": 1030976843,
        "order_id": 450789469,
        "refund_id": 929361466,
        "amount": "-5.00",
        "tax_amount": "0.00",
        "kind": "shipping_refund",
        "reason": "Shipping refund",
        "amount_set": {
          "shop_money": {
            "amount": "-5.00",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "-5.00",
            "currency_code": "USD"
          }
        },
        "tax_amount_set": {
          "shop_money": {
            "amount": "0.00",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "0.00",
            "currency_code": "USD"
          }
        }
      }
    ]
  }
}
Version 2020-01

Important

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
read-only 
"created_at": "2008-01-10T11:00:00-05:00"

The date and time (ISO 8601 format) when the refund was created.
id
read-only 
"id": 92738740

The unique identifier for the refund.
note 
"note": "Item was damaged during shipping"

An optional note attached to a refund.
order_adjustments
read-only 
"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 
"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 
"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,
        "currency_code": "USD"
      }
    },
    "total_tax_set": {
      "shop_money": {
        "amount": 1.67,
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": 1.32,
        "currency_code": "USD"
      }
    }
  }
]

A list of refunded line items. Each entry has the following properties:

  • id: The unique identifier of the line item in the refund.
  • line_item: A line item being returned.
  • line_item_id: The ID of the related line item in the order.
  • quantity: The quantity of the associated line item that was returned.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory. The number of fulfillable units for this line item will remain unchanged. For example, a refund payment can be issued but no items will be returned or made available for sale again.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered, and will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
    • legacy_restock: The deprecated restock property was used for this refund. These items were made available for sale again. This value is not accepted when creating new refunds.
  • location_id: The unique identifier of the location where the items will be restocked. Required when restock_type has the value return or cancel.
  • subtotal: The subtotal of the refund line item.
  • total_tax: The total tax on the refund line item.
  • subtotal_set: The subtotal of the refund line item in shop and presentment currencies.
  • total_tax_set: The total tax of the line item in shop and presentment currencies.
restock
deprecated 
"restock": true

Whether to add the line items back to the store's inventory.

Provide a restock_type to influence how this refund affects inventory instead
transactions 
"transactions": [
  {
    "id": 179259969,
    "order_id": 450789469,
    "amount": "209.00",
    "kind": "refund",
    "gateway": "shopify_payments",
    "status": "success",
    "message": null,
    "created_at": "2005-08-05T12:59:12-04:00",
    "test": false,
    "authorization": "authorization-key",
    "currency": "USD",
    "location_id": null,
    "user_id": null,
    "parent_id": 801038806,
    "device_id": null,
    "receipt": {},
    "error_code": null,
    "source_name": "web"
  }
]

A list of transactions involved in the refund. For more information, see the Transaction resource.
user_id 
"user_id": 238478920

The unique identifier of the user who performed the refund.

Endpoints

GET /admin/api/2020-01/orders/{order_id}/refunds.json
Retrieves a list of refunds for an order. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency

Show amounts in the shop currency for the underlying transaction.

(default: false)

Retrieve all refunds from a specific order

GET /admin/api/2020-07/orders/450789469/refunds.json
View Response 
HTTP/1.1 200 OK
{
  "refunds": [
    {
      "id": 509562969,
      "order_id": 450789469,
      "created_at": "2020-09-08T13:05:54-04:00",
      "note": "it broke during shipping",
      "user_id": 799407056,
      "processed_at": "2020-09-08T13:05:54-04:00",
      "restock": true,
      "duties": [],
      "admin_graphql_api_id": "gid://shopify/Refund/509562969",
      "refund_line_items": [
        {
          "id": 104689539,
          "quantity": 1,
          "line_item_id": 703073504,
          "location_id": 487838322,
          "restock_type": "legacy_restock",
          "subtotal": 195.67,
          "total_tax": 3.98,
          "subtotal_set": {
            "shop_money": {
              "amount": "195.67",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "195.67",
              "currency_code": "USD"
            }
          },
          "total_tax_set": {
            "shop_money": {
              "amount": "3.98",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "3.98",
              "currency_code": "USD"
            }
          },
          "line_item": {
            "id": 703073504,
            "variant_id": 457924702,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "sku": "IPOD2008BLACK",
            "variant_title": "black",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - black",
            "variant_inventory_management": "shopify",
            "properties": [],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "price": "199.00",
            "total_discount": "0.00",
            "fulfillment_status": null,
            "price_set": {
              "shop_money": {
                "amount": "199.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "199.00",
                "currency_code": "USD"
              }
            },
            "total_discount_set": {
              "shop_money": {
                "amount": "0.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "0.00",
                "currency_code": "USD"
              }
            },
            "discount_allocations": [
              {
                "amount": "3.33",
                "discount_application_index": 0,
                "amount_set": {
                  "shop_money": {
                    "amount": "3.33",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.33",
                    "currency_code": "USD"
                  }
                }
              }
            ],
            "duties": [],
            "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06,
                "price_set": {
                  "shop_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  }
                }
              }
            ]
          }
        },
        {
          "id": 709875399,
          "quantity": 1,
          "line_item_id": 466157049,
          "location_id": 487838322,
          "restock_type": "legacy_restock",
          "subtotal": 195.66,
          "total_tax": 3.98,
          "subtotal_set": {
            "shop_money": {
              "amount": "195.66",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "195.66",
              "currency_code": "USD"
            }
          },
          "total_tax_set": {
            "shop_money": {
              "amount": "3.98",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "3.98",
              "currency_code": "USD"
            }
          },
          "line_item": {
            "id": 466157049,
            "variant_id": 39072856,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "sku": "IPOD2008GREEN",
            "variant_title": "green",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - green",
            "variant_inventory_management": "shopify",
            "properties": [
              {
                "name": "Custom Engraving Front",
                "value": "Happy Birthday"
              },
              {
                "name": "Custom Engraving Back",
                "value": "Merry Christmas"
              }
            ],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "price": "199.00",
            "total_discount": "0.00",
            "fulfillment_status": null,
            "price_set": {
              "shop_money": {
                "amount": "199.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "199.00",
                "currency_code": "USD"
              }
            },
            "total_discount_set": {
              "shop_money": {
                "amount": "0.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "0.00",
                "currency_code": "USD"
              }
            },
            "discount_allocations": [
              {
                "amount": "3.34",
                "discount_application_index": 0,
                "amount_set": {
                  "shop_money": {
                    "amount": "3.34",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.34",
                    "currency_code": "USD"
                  }
                }
              }
            ],
            "duties": [],
            "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06,
                "price_set": {
                  "shop_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  }
                }
              }
            ]
          }
        }
      ],
      "transactions": [
        {
          "id": 179259969,
          "order_id": 450789469,
          "kind": "refund",
          "gateway": "bogus",
          "status": "success",
          "message": null,
          "created_at": "2005-08-05T12:59:12-04:00",
          "test": false,
          "authorization": "authorization-key",
          "location_id": null,
          "user_id": null,
          "parent_id": 801038806,
          "processed_at": "2005-08-05T12:59:12-04:00",
          "device_id": null,
          "receipt": {},
          "error_code": null,
          "source_name": "web",
          "currency_exchange_adjustment": null,
          "amount": "209.00",
          "currency": "USD",
          "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
        }
      ],
      "order_adjustments": []
    }
  ]
}
GET /admin/api/2020-01/orders/{order_id}/refunds/{refund_id}.json
Retrieves a specific refund.
fields

Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency

Show amounts in the shop currency for the underlying transaction.

(default: false)

Retrieve a specific refund

GET /admin/api/2020-07/orders/450789469/refunds/509562969.json
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "id": 509562969,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:05:54-04:00",
    "note": "it broke during shipping",
    "user_id": 799407056,
    "processed_at": "2020-09-08T13:05:54-04:00",
    "restock": true,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/509562969",
    "refund_line_items": [
      {
        "id": 104689539,
        "quantity": 1,
        "line_item_id": 703073504,
        "location_id": 487838322,
        "restock_type": "legacy_restock",
        "subtotal": 195.67,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.67",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.67",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 703073504,
          "variant_id": 457924702,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008BLACK",
          "variant_title": "black",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - black",
          "variant_inventory_management": "shopify",
          "properties": [],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.33",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      },
      {
        "id": 709875399,
        "quantity": 1,
        "line_item_id": 466157049,
        "location_id": 487838322,
        "restock_type": "legacy_restock",
        "subtotal": 195.66,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.66",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.66",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 466157049,
          "variant_id": 39072856,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008GREEN",
          "variant_title": "green",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - green",
          "variant_inventory_management": "shopify",
          "properties": [
            {
              "name": "Custom Engraving Front",
              "value": "Happy Birthday"
            },
            {
              "name": "Custom Engraving Back",
              "value": "Merry Christmas"
            }
          ],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.34",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 179259969,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": null,
        "created_at": "2005-08-05T12:59:12-04:00",
        "test": false,
        "authorization": "authorization-key",
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2005-08-05T12:59:12-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "web",
        "currency_exchange_adjustment": null,
        "amount": "209.00",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
      }
    ],
    "order_adjustments": []
  }
}
POST /admin/api/2020-01/orders/{order_id}/refunds/calculate.json

Calculates refund transactions based on line items and shipping. When you want to create a refund, you should first 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 intend to refund shipping costs. If the restock instructions can't be met—for example, because you try to return more items than have been fulfilled—then the endpoint returns modified restock instructions. You can then use the response in the body of the request to create the actual refund.

The response includes a transactions object with "kind": "suggested_refund", which must to be changed to "kind" : "refund" for the refund to be accepted.

shipping

Specify how much shipping to refund. It has the following properties:

  • full_refund: Whether to refund all remaining shipping.
  • amount: Set a specific amount to refund for shipping. Takes precedence over full_refund.
refund_line_items

A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:

  • line_item_id: The ID of a line item to refund.
  • quantity: The quantity to refund.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered but will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
  • location_id: The ID of the location where the items should be restocked. If location_id is not provided and the value of restock_type is return or cancel, then the endpoint returns a suitable location ID.
  • already_stocked: Whether the item is already stocked at the location. If this is false, then creating the refund will connect the item to the location and start stocking it there.
currency

The three-letter code (ISO 4217 format) for the currency used for the refund. Note: Required whenever the shipping amount property is provided.

Calculate the refund without specifying currency

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "no_restock"
      }
    ]
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "5.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [
      {
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": null,
        "restock_type": "no_restock",
        "price": "199.00",
        "subtotal": "195.67",
        "total_tax": "3.98",
        "discounted_price": "199.00",
        "discounted_total_price": "199.00",
        "total_cart_discount_amount": "3.33"
      }
    ],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "41.94",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}

Calculate the refund for a line item and shipping

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "no_restock"
      }
    ]
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "5.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [
      {
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": null,
        "restock_type": "no_restock",
        "price": "199.00",
        "subtotal": "195.67",
        "total_tax": "3.98",
        "discounted_price": "199.00",
        "discounted_total_price": "199.00",
        "total_cart_discount_amount": "3.33"
      }
    ],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "41.94",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}

Calculate a refund for a partial amount of shipping

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "amount": 2.0
    }
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "2.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "2.00",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}
POST /admin/api/2020-01/orders/{order_id}/refunds.json

Creates a refund. Use the calculate endpoint to produce the transactions to submit.


restock
deprecated

Whether to add the line items back to the store inventory. Use restock_type for refund line items instead.
notify

Whether to send a refund notification to the customer.
note

An optional note attached to a refund.
discrepancy_reason

An optional comment that explains a discrepancy between calculated and actual refund amounts. Used to populate the reason property of the resulting order adjustment object attached to the refund. Valid values: restock, damage, customer, and other.
shipping

Specify how much shipping to refund. It has the following properties:

  • full_refund: Whether to refund all remaining shipping.
  • amount: Set a specific amount to refund for shipping. Takes precedence over full_refund.
refund_line_items

A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:

  • line_item_id: The ID of a line item to refund.
  • quantity: The quantity to refund.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered but will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
  • location_id: The ID of the location where the items should be restocked. This is required when the value of restock_type is return or cancel. If the item is not already stocked at the location, then the item is connected to the location. An error is returned when the item is connected to a fulfillment service location and a different location is provided.
transactions

A list of transactions to process as refunds.

currency

The three-letter code (ISO 4217 format) for the currency used for the refund.

Create a refund for an order

POST /admin/api/2020-07/orders/450789469/refunds.json
{
  "refund": {
    "currency": "USD",
    "notify": true,
    "note": "wrong size",
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "return",
        "location_id": 487838322
      }
    ],
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 41.94,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
View Response 
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361465,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:24:21-04:00",
    "note": "wrong size",
    "user_id": null,
    "processed_at": "2020-09-08T13:24:21-04:00",
    "restock": true,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/929361465",
    "refund_line_items": [
      {
        "id": 1058498312,
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": 487838322,
        "restock_type": "return",
        "subtotal": 195.67,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.67",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.67",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 518995019,
          "variant_id": 49148385,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008RED",
          "variant_title": "red",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - red",
          "variant_inventory_management": "shopify",
          "properties": [],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.33",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/518995019",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 1072844691,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2020-09-08T13:24:21-04:00",
        "test": true,
        "authorization": null,
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2020-09-08T13:24:21-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713",
        "currency_exchange_adjustment": null,
        "amount": "41.94",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844691"
      }
    ],
    "order_adjustments": []
  }
}

Refund a specific amount of shipping

POST /admin/api/2020-07/orders/450789469/refunds.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "amount": 5.0
    },
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 5.0,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
View Response 
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361466,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:24:23-04:00",
    "note": null,
    "user_id": null,
    "processed_at": "2020-09-08T13:24:23-04:00",
    "restock": false,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/929361466",
    "refund_line_items": [],
    "transactions": [
      {
        "id": 1072844692,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2020-09-08T13:24:23-04:00",
        "test": true,
        "authorization": null,
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2020-09-08T13:24:23-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713",
        "currency_exchange_adjustment": null,
        "amount": "5.00",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844692"
      }
    ],
    "order_adjustments": [
      {
        "id": 1030976843,
        "order_id": 450789469,
        "refund_id": 929361466,
        "amount": "-5.00",
        "tax_amount": "0.00",
        "kind": "shipping_refund",
        "reason": "Shipping refund",
        "amount_set": {
          "shop_money": {
            "amount": "-5.00",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "-5.00",
            "currency_code": "USD"
          }
        },
        "tax_amount_set": {
          "shop_money": {
            "amount": "0.00",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "0.00",
            "currency_code": "USD"
          }
        }
      }
    ]
  }
}
Version 2020-04

Important

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
read-only 
"created_at": "2008-01-10T11:00:00-05:00"

The date and time (ISO 8601 format) when the refund was created.
duties
read-only 
"duties": [
  {
    "duty_id": 1,
    "amount_set": {
      "shop_money": {
        "amount": "9.83",
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": "9.83",
        "currency_code": "CAD"
      }
    }
  }
]

A list of duties that have been returned as part of the refund.
id
read-only 
"id": 92738740

The unique identifier for the refund.
note 
"note": "Item was damaged during shipping"

An optional note attached to a refund.
order_adjustments
read-only 
"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 
"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 
"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,
        "currency_code": "USD"
      }
    },
    "total_tax_set": {
      "shop_money": {
        "amount": 1.67,
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": 1.32,
        "currency_code": "USD"
      }
    }
  }
]

A list of refunded line items. Each entry has the following properties:

  • id: The unique identifier of the line item in the refund.
  • line_item: A line item being returned.
  • line_item_id: The ID of the related line item in the order.
  • quantity: The quantity of the associated line item that was returned.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory. The number of fulfillable units for this line item will remain unchanged. For example, a refund payment can be issued but no items will be returned or made available for sale again.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered, and will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
    • legacy_restock: The deprecated restock property was used for this refund. These items were made available for sale again. This value is not accepted when creating new refunds.
  • location_id: The unique identifier of the location where the items will be restocked. Required when restock_type has the value return or cancel.
  • subtotal: The subtotal of the refund line item.
  • total_tax: The total tax on the refund line item.
  • subtotal_set: The subtotal of the refund line item in shop and presentment currencies.
  • total_tax_set: The total tax of the line item in shop and presentment currencies.
restock
deprecated 
"restock": true

Whether to add the line items back to the store's inventory.

Provide a restock_type to influence how this refund affects inventory instead
transactions 
"transactions": [
  {
    "id": 179259969,
    "order_id": 450789469,
    "amount": "209.00",
    "kind": "refund",
    "gateway": "shopify_payments",
    "status": "success",
    "message": null,
    "created_at": "2005-08-05T12:59:12-04:00",
    "test": false,
    "authorization": "authorization-key",
    "currency": "USD",
    "location_id": null,
    "user_id": null,
    "parent_id": 801038806,
    "device_id": null,
    "receipt": {},
    "error_code": null,
    "source_name": "web"
  }
]

A list of transactions involved in the refund. For more information, see the Transaction resource.
user_id 
"user_id": 238478920

The unique identifier of the user who performed the refund.

Endpoints

GET /admin/api/2020-04/orders/{order_id}/refunds.json
Retrieves a list of refunds for an order. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency

Show amounts in the shop currency for the underlying transaction.

(default: false)

Retrieve all refunds from a specific order

GET /admin/api/2020-07/orders/450789469/refunds.json
View Response 
HTTP/1.1 200 OK
{
  "refunds": [
    {
      "id": 509562969,
      "order_id": 450789469,
      "created_at": "2020-09-08T13:05:54-04:00",
      "note": "it broke during shipping",
      "user_id": 799407056,
      "processed_at": "2020-09-08T13:05:54-04:00",
      "restock": true,
      "duties": [],
      "admin_graphql_api_id": "gid://shopify/Refund/509562969",
      "refund_line_items": [
        {
          "id": 104689539,
          "quantity": 1,
          "line_item_id": 703073504,
          "location_id": 487838322,
          "restock_type": "legacy_restock",
          "subtotal": 195.67,
          "total_tax": 3.98,
          "subtotal_set": {
            "shop_money": {
              "amount": "195.67",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "195.67",
              "currency_code": "USD"
            }
          },
          "total_tax_set": {
            "shop_money": {
              "amount": "3.98",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "3.98",
              "currency_code": "USD"
            }
          },
          "line_item": {
            "id": 703073504,
            "variant_id": 457924702,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "sku": "IPOD2008BLACK",
            "variant_title": "black",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - black",
            "variant_inventory_management": "shopify",
            "properties": [],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "price": "199.00",
            "total_discount": "0.00",
            "fulfillment_status": null,
            "price_set": {
              "shop_money": {
                "amount": "199.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "199.00",
                "currency_code": "USD"
              }
            },
            "total_discount_set": {
              "shop_money": {
                "amount": "0.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "0.00",
                "currency_code": "USD"
              }
            },
            "discount_allocations": [
              {
                "amount": "3.33",
                "discount_application_index": 0,
                "amount_set": {
                  "shop_money": {
                    "amount": "3.33",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.33",
                    "currency_code": "USD"
                  }
                }
              }
            ],
            "duties": [],
            "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06,
                "price_set": {
                  "shop_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  }
                }
              }
            ]
          }
        },
        {
          "id": 709875399,
          "quantity": 1,
          "line_item_id": 466157049,
          "location_id": 487838322,
          "restock_type": "legacy_restock",
          "subtotal": 195.66,
          "total_tax": 3.98,
          "subtotal_set": {
            "shop_money": {
              "amount": "195.66",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "195.66",
              "currency_code": "USD"
            }
          },
          "total_tax_set": {
            "shop_money": {
              "amount": "3.98",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "3.98",
              "currency_code": "USD"
            }
          },
          "line_item": {
            "id": 466157049,
            "variant_id": 39072856,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "sku": "IPOD2008GREEN",
            "variant_title": "green",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - green",
            "variant_inventory_management": "shopify",
            "properties": [
              {
                "name": "Custom Engraving Front",
                "value": "Happy Birthday"
              },
              {
                "name": "Custom Engraving Back",
                "value": "Merry Christmas"
              }
            ],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "price": "199.00",
            "total_discount": "0.00",
            "fulfillment_status": null,
            "price_set": {
              "shop_money": {
                "amount": "199.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "199.00",
                "currency_code": "USD"
              }
            },
            "total_discount_set": {
              "shop_money": {
                "amount": "0.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "0.00",
                "currency_code": "USD"
              }
            },
            "discount_allocations": [
              {
                "amount": "3.34",
                "discount_application_index": 0,
                "amount_set": {
                  "shop_money": {
                    "amount": "3.34",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.34",
                    "currency_code": "USD"
                  }
                }
              }
            ],
            "duties": [],
            "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06,
                "price_set": {
                  "shop_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  }
                }
              }
            ]
          }
        }
      ],
      "transactions": [
        {
          "id": 179259969,
          "order_id": 450789469,
          "kind": "refund",
          "gateway": "bogus",
          "status": "success",
          "message": null,
          "created_at": "2005-08-05T12:59:12-04:00",
          "test": false,
          "authorization": "authorization-key",
          "location_id": null,
          "user_id": null,
          "parent_id": 801038806,
          "processed_at": "2005-08-05T12:59:12-04:00",
          "device_id": null,
          "receipt": {},
          "error_code": null,
          "source_name": "web",
          "currency_exchange_adjustment": null,
          "amount": "209.00",
          "currency": "USD",
          "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
        }
      ],
      "order_adjustments": []
    }
  ]
}
GET /admin/api/2020-04/orders/{order_id}/refunds/{refund_id}.json
Retrieves a specific refund.
fields

Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency

Show amounts in the shop currency for the underlying transaction.

(default: false)

Retrieve a specific refund

GET /admin/api/2020-07/orders/450789469/refunds/509562969.json
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "id": 509562969,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:05:54-04:00",
    "note": "it broke during shipping",
    "user_id": 799407056,
    "processed_at": "2020-09-08T13:05:54-04:00",
    "restock": true,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/509562969",
    "refund_line_items": [
      {
        "id": 104689539,
        "quantity": 1,
        "line_item_id": 703073504,
        "location_id": 487838322,
        "restock_type": "legacy_restock",
        "subtotal": 195.67,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.67",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.67",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 703073504,
          "variant_id": 457924702,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008BLACK",
          "variant_title": "black",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - black",
          "variant_inventory_management": "shopify",
          "properties": [],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.33",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      },
      {
        "id": 709875399,
        "quantity": 1,
        "line_item_id": 466157049,
        "location_id": 487838322,
        "restock_type": "legacy_restock",
        "subtotal": 195.66,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.66",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.66",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 466157049,
          "variant_id": 39072856,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008GREEN",
          "variant_title": "green",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - green",
          "variant_inventory_management": "shopify",
          "properties": [
            {
              "name": "Custom Engraving Front",
              "value": "Happy Birthday"
            },
            {
              "name": "Custom Engraving Back",
              "value": "Merry Christmas"
            }
          ],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.34",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 179259969,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": null,
        "created_at": "2005-08-05T12:59:12-04:00",
        "test": false,
        "authorization": "authorization-key",
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2005-08-05T12:59:12-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "web",
        "currency_exchange_adjustment": null,
        "amount": "209.00",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
      }
    ],
    "order_adjustments": []
  }
}
POST /admin/api/2020-04/orders/{order_id}/refunds/calculate.json

Calculates refund transactions based on line items and shipping. When you want to create a refund, you should first 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 intend to refund shipping costs. If the restock instructions can't be met—for example, because you try to return more items than have been fulfilled—then the endpoint returns modified restock instructions. You can then use the response in the body of the request to create the actual refund.

The response includes a transactions object with "kind": "suggested_refund", which must to be changed to "kind" : "refund" for the refund to be accepted.

shipping

Specify how much shipping to refund. It has the following properties:

  • full_refund: Whether to refund all remaining shipping.
  • amount: Set a specific amount to refund for shipping. Takes precedence over full_refund.
refund_line_items

A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:

  • line_item_id: The ID of a line item to refund.
  • quantity: The quantity to refund.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered but will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
  • location_id: The ID of the location where the items should be restocked. If location_id is not provided and the value of restock_type is return or cancel, then the endpoint returns a suitable location ID.
  • already_stocked: Whether the item is already stocked at the location. If this is false, then creating the refund will connect the item to the location and start stocking it there.
currency

The three-letter code (ISO 4217 format) for the currency used for the refund. Note: Required whenever the shipping amount property is provided.

Calculate the refund without specifying currency

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "no_restock"
      }
    ]
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "5.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [
      {
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": null,
        "restock_type": "no_restock",
        "price": "199.00",
        "subtotal": "195.67",
        "total_tax": "3.98",
        "discounted_price": "199.00",
        "discounted_total_price": "199.00",
        "total_cart_discount_amount": "3.33"
      }
    ],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "41.94",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}

Calculate the refund for a line item and shipping

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "no_restock"
      }
    ]
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "5.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [
      {
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": null,
        "restock_type": "no_restock",
        "price": "199.00",
        "subtotal": "195.67",
        "total_tax": "3.98",
        "discounted_price": "199.00",
        "discounted_total_price": "199.00",
        "total_cart_discount_amount": "3.33"
      }
    ],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "41.94",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}

Calculate a refund for a partial amount of shipping

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "amount": 2.0
    }
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "2.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "2.00",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}
POST /admin/api/2020-04/orders/{order_id}/refunds.json

Creates a refund. Use the calculate endpoint to produce the transactions to submit.


restock
deprecated

Whether to add the line items back to the store inventory. Use restock_type for refund line items instead.
notify

Whether to send a refund notification to the customer.
note

An optional note attached to a refund.
discrepancy_reason

An optional comment that explains a discrepancy between calculated and actual refund amounts. Used to populate the reason property of the resulting order adjustment object attached to the refund. Valid values: restock, damage, customer, and other.
shipping

Specify how much shipping to refund. It has the following properties:

  • full_refund: Whether to refund all remaining shipping.
  • amount: Set a specific amount to refund for shipping. Takes precedence over full_refund.
refund_line_items

A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:

  • line_item_id: The ID of a line item to refund.
  • quantity: The quantity to refund.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered but will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
  • location_id: The ID of the location where the items should be restocked. This is required when the value of restock_type is return or cancel. If the item is not already stocked at the location, then the item is connected to the location. An error is returned when the item is connected to a fulfillment service location and a different location is provided.
transactions

A list of transactions to process as refunds.

currency

The three-letter code (ISO 4217 format) for the currency used for the refund.

Create a refund for an order

POST /admin/api/2020-07/orders/450789469/refunds.json
{
  "refund": {
    "currency": "USD",
    "notify": true,
    "note": "wrong size",
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "return",
        "location_id": 487838322
      }
    ],
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 41.94,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
View Response 
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361465,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:24:21-04:00",
    "note": "wrong size",
    "user_id": null,
    "processed_at": "2020-09-08T13:24:21-04:00",
    "restock": true,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/929361465",
    "refund_line_items": [
      {
        "id": 1058498312,
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": 487838322,
        "restock_type": "return",
        "subtotal": 195.67,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.67",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.67",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 518995019,
          "variant_id": 49148385,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008RED",
          "variant_title": "red",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - red",
          "variant_inventory_management": "shopify",
          "properties": [],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.33",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/518995019",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 1072844691,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2020-09-08T13:24:21-04:00",
        "test": true,
        "authorization": null,
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2020-09-08T13:24:21-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713",
        "currency_exchange_adjustment": null,
        "amount": "41.94",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844691"
      }
    ],
    "order_adjustments": []
  }
}

Refund a specific amount of shipping

POST /admin/api/2020-07/orders/450789469/refunds.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "amount": 5.0
    },
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 5.0,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
View Response 
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361466,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:24:23-04:00",
    "note": null,
    "user_id": null,
    "processed_at": "2020-09-08T13:24:23-04:00",
    "restock": false,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/929361466",
    "refund_line_items": [],
    "transactions": [
      {
        "id": 1072844692,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2020-09-08T13:24:23-04:00",
        "test": true,
        "authorization": null,
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2020-09-08T13:24:23-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713",
        "currency_exchange_adjustment": null,
        "amount": "5.00",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844692"
      }
    ],
    "order_adjustments": [
      {
        "id": 1030976843,
        "order_id": 450789469,
        "refund_id": 929361466,
        "amount": "-5.00",
        "tax_amount": "0.00",
        "kind": "shipping_refund",
        "reason": "Shipping refund",
        "amount_set": {
          "shop_money": {
            "amount": "-5.00",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "-5.00",
            "currency_code": "USD"
          }
        },
        "tax_amount_set": {
          "shop_money": {
            "amount": "0.00",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "0.00",
            "currency_code": "USD"
          }
        }
      }
    ]
  }
}
Version 2020-07 (Latest)

Important

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
read-only 
"created_at": "2008-01-10T11:00:00-05:00"

The date and time (ISO 8601 format) when the refund was created.
duties
read-only 
"duties": [
  {
    "duty_id": 1,
    "amount_set": {
      "shop_money": {
        "amount": "9.83",
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": "9.83",
        "currency_code": "CAD"
      }
    }
  }
]

A list of duties that have been returned as part of the refund.
id
read-only 
"id": 92738740

The unique identifier for the refund.
note 
"note": "Item was damaged during shipping"

An optional note attached to a refund.
order_adjustments
read-only 
"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 
"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 
"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,
        "currency_code": "USD"
      }
    },
    "total_tax_set": {
      "shop_money": {
        "amount": 1.67,
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": 1.32,
        "currency_code": "USD"
      }
    }
  }
]

A list of refunded line items. Each entry has the following properties:

  • id: The unique identifier of the line item in the refund.
  • line_item: A line item being returned.
  • line_item_id: The ID of the related line item in the order.
  • quantity: The quantity of the associated line item that was returned.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory. The number of fulfillable units for this line item will remain unchanged. For example, a refund payment can be issued but no items will be returned or made available for sale again.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered, and will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
    • legacy_restock: The deprecated restock property was used for this refund. These items were made available for sale again. This value is not accepted when creating new refunds.
  • location_id: The unique identifier of the location where the items will be restocked. Required when restock_type has the value return or cancel.
  • subtotal: The subtotal of the refund line item.
  • total_tax: The total tax on the refund line item.
  • subtotal_set: The subtotal of the refund line item in shop and presentment currencies.
  • total_tax_set: The total tax of the line item in shop and presentment currencies.
restock
deprecated 
"restock": true

Whether to add the line items back to the store's inventory.

Provide a restock_type to influence how this refund affects inventory instead
transactions 
"transactions": [
  {
    "id": 179259969,
    "order_id": 450789469,
    "amount": "209.00",
    "kind": "refund",
    "gateway": "shopify_payments",
    "status": "success",
    "message": null,
    "created_at": "2005-08-05T12:59:12-04:00",
    "test": false,
    "authorization": "authorization-key",
    "currency": "USD",
    "location_id": null,
    "user_id": null,
    "parent_id": 801038806,
    "device_id": null,
    "receipt": {},
    "error_code": null,
    "source_name": "web"
  }
]

A list of transactions involved in the refund. For more information, see the Transaction resource.
user_id 
"user_id": 238478920

The unique identifier of the user who performed the refund.

Endpoints

GET /admin/api/2020-07/orders/{order_id}/refunds.json
Retrieves a list of refunds for an order. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency

Show amounts in the shop currency for the underlying transaction.

(default: false)

Retrieve all refunds from a specific order

GET /admin/api/2020-07/orders/450789469/refunds.json
View Response 
HTTP/1.1 200 OK
{
  "refunds": [
    {
      "id": 509562969,
      "order_id": 450789469,
      "created_at": "2020-09-08T13:05:54-04:00",
      "note": "it broke during shipping",
      "user_id": 799407056,
      "processed_at": "2020-09-08T13:05:54-04:00",
      "restock": true,
      "duties": [],
      "admin_graphql_api_id": "gid://shopify/Refund/509562969",
      "refund_line_items": [
        {
          "id": 104689539,
          "quantity": 1,
          "line_item_id": 703073504,
          "location_id": 487838322,
          "restock_type": "legacy_restock",
          "subtotal": 195.67,
          "total_tax": 3.98,
          "subtotal_set": {
            "shop_money": {
              "amount": "195.67",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "195.67",
              "currency_code": "USD"
            }
          },
          "total_tax_set": {
            "shop_money": {
              "amount": "3.98",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "3.98",
              "currency_code": "USD"
            }
          },
          "line_item": {
            "id": 703073504,
            "variant_id": 457924702,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "sku": "IPOD2008BLACK",
            "variant_title": "black",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - black",
            "variant_inventory_management": "shopify",
            "properties": [],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "price": "199.00",
            "total_discount": "0.00",
            "fulfillment_status": null,
            "price_set": {
              "shop_money": {
                "amount": "199.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "199.00",
                "currency_code": "USD"
              }
            },
            "total_discount_set": {
              "shop_money": {
                "amount": "0.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "0.00",
                "currency_code": "USD"
              }
            },
            "discount_allocations": [
              {
                "amount": "3.33",
                "discount_application_index": 0,
                "amount_set": {
                  "shop_money": {
                    "amount": "3.33",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.33",
                    "currency_code": "USD"
                  }
                }
              }
            ],
            "duties": [],
            "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06,
                "price_set": {
                  "shop_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  }
                }
              }
            ]
          }
        },
        {
          "id": 709875399,
          "quantity": 1,
          "line_item_id": 466157049,
          "location_id": 487838322,
          "restock_type": "legacy_restock",
          "subtotal": 195.66,
          "total_tax": 3.98,
          "subtotal_set": {
            "shop_money": {
              "amount": "195.66",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "195.66",
              "currency_code": "USD"
            }
          },
          "total_tax_set": {
            "shop_money": {
              "amount": "3.98",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "3.98",
              "currency_code": "USD"
            }
          },
          "line_item": {
            "id": 466157049,
            "variant_id": 39072856,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "sku": "IPOD2008GREEN",
            "variant_title": "green",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - green",
            "variant_inventory_management": "shopify",
            "properties": [
              {
                "name": "Custom Engraving Front",
                "value": "Happy Birthday"
              },
              {
                "name": "Custom Engraving Back",
                "value": "Merry Christmas"
              }
            ],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "price": "199.00",
            "total_discount": "0.00",
            "fulfillment_status": null,
            "price_set": {
              "shop_money": {
                "amount": "199.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "199.00",
                "currency_code": "USD"
              }
            },
            "total_discount_set": {
              "shop_money": {
                "amount": "0.00",
                "currency_code": "USD"
              },
              "presentment_money": {
                "amount": "0.00",
                "currency_code": "USD"
              }
            },
            "discount_allocations": [
              {
                "amount": "3.34",
                "discount_application_index": 0,
                "amount_set": {
                  "shop_money": {
                    "amount": "3.34",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.34",
                    "currency_code": "USD"
                  }
                }
              }
            ],
            "duties": [],
            "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06,
                "price_set": {
                  "shop_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "3.98",
                    "currency_code": "USD"
                  }
                }
              }
            ]
          }
        }
      ],
      "transactions": [
        {
          "id": 179259969,
          "order_id": 450789469,
          "kind": "refund",
          "gateway": "bogus",
          "status": "success",
          "message": null,
          "created_at": "2005-08-05T12:59:12-04:00",
          "test": false,
          "authorization": "authorization-key",
          "location_id": null,
          "user_id": null,
          "parent_id": 801038806,
          "processed_at": "2005-08-05T12:59:12-04:00",
          "device_id": null,
          "receipt": {},
          "error_code": null,
          "source_name": "web",
          "currency_exchange_adjustment": null,
          "amount": "209.00",
          "currency": "USD",
          "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
        }
      ],
      "order_adjustments": []
    }
  ]
}
GET /admin/api/2020-07/orders/{order_id}/refunds/{refund_id}.json
Retrieves a specific refund.
fields

Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency

Show amounts in the shop currency for the underlying transaction.

(default: false)

Retrieve a specific refund

GET /admin/api/2020-07/orders/450789469/refunds/509562969.json
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "id": 509562969,
    "order_id": 450789469,
    "created_at": "2020-09-08T13:05:54-04:00",
    "note": "it broke during shipping",
    "user_id": 799407056,
    "processed_at": "2020-09-08T13:05:54-04:00",
    "restock": true,
    "duties": [],
    "admin_graphql_api_id": "gid://shopify/Refund/509562969",
    "refund_line_items": [
      {
        "id": 104689539,
        "quantity": 1,
        "line_item_id": 703073504,
        "location_id": 487838322,
        "restock_type": "legacy_restock",
        "subtotal": 195.67,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.67",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.67",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 703073504,
          "variant_id": 457924702,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008BLACK",
          "variant_title": "black",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - black",
          "variant_inventory_management": "shopify",
          "properties": [],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.33",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      },
      {
        "id": 709875399,
        "quantity": 1,
        "line_item_id": 466157049,
        "location_id": 487838322,
        "restock_type": "legacy_restock",
        "subtotal": 195.66,
        "total_tax": 3.98,
        "subtotal_set": {
          "shop_money": {
            "amount": "195.66",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "195.66",
            "currency_code": "USD"
          }
        },
        "total_tax_set": {
          "shop_money": {
            "amount": "3.98",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "3.98",
            "currency_code": "USD"
          }
        },
        "line_item": {
          "id": 466157049,
          "variant_id": 39072856,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "sku": "IPOD2008GREEN",
          "variant_title": "green",
          "vendor": null,
          "fulfillment_service": "manual",
          "product_id": 632910392,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "name": "IPod Nano - 8gb - green",
          "variant_inventory_management": "shopify",
          "properties": [
            {
              "name": "Custom Engraving Front",
              "value": "Happy Birthday"
            },
            {
              "name": "Custom Engraving Back",
              "value": "Merry Christmas"
            }
          ],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.34",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 179259969,
        "order_id": 450789469,
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": null,
        "created_at": "2005-08-05T12:59:12-04:00",
        "test": false,
        "authorization": "authorization-key",
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "processed_at": "2005-08-05T12:59:12-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "web",
        "currency_exchange_adjustment": null,
        "amount": "209.00",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
      }
    ],
    "order_adjustments": []
  }
}
POST /admin/api/2020-07/orders/{order_id}/refunds/calculate.json

Calculates refund transactions based on line items and shipping. When you want to create a refund, you should first 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 intend to refund shipping costs. If the restock instructions can't be met—for example, because you try to return more items than have been fulfilled—then the endpoint returns modified restock instructions. You can then use the response in the body of the request to create the actual refund.

The response includes a transactions object with "kind": "suggested_refund", which must to be changed to "kind" : "refund" for the refund to be accepted.

shipping

Specify how much shipping to refund. It has the following properties:

  • full_refund: Whether to refund all remaining shipping.
  • amount: Set a specific amount to refund for shipping. Takes precedence over full_refund.
refund_line_items

A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:

  • line_item_id: The ID of a line item to refund.
  • quantity: The quantity to refund.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered but will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
  • location_id: The ID of the location where the items should be restocked. If location_id is not provided and the value of restock_type is return or cancel, then the endpoint returns a suitable location ID.
  • already_stocked: Whether the item is already stocked at the location. If this is false, then creating the refund will connect the item to the location and start stocking it there.
currency

The three-letter code (ISO 4217 format) for the currency used for the refund. Note: Required whenever the shipping amount property is provided.

Calculate the refund without specifying currency

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "no_restock"
      }
    ]
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "5.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [
      {
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": null,
        "restock_type": "no_restock",
        "price": "199.00",
        "subtotal": "195.67",
        "total_tax": "3.98",
        "discounted_price": "199.00",
        "discounted_total_price": "199.00",
        "total_cart_discount_amount": "3.33"
      }
    ],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "41.94",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}

Calculate the refund for a line item and shipping

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "no_restock"
      }
    ]
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "5.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [
      {
        "quantity": 1,
        "line_item_id": 518995019,
        "location_id": null,
        "restock_type": "no_restock",
        "price": "199.00",
        "subtotal": "195.67",
        "total_tax": "3.98",
        "discounted_price": "199.00",
        "discounted_total_price": "199.00",
        "total_cart_discount_amount": "3.33"
      }
    ],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "41.94",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}

Calculate a refund for a partial amount of shipping

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json
{
  "refund": {
    "currency": "USD",
    "shipping": {
      "amount": 2.0
    }
  }
}
View Response 
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "2.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "duties": [],
    "refund_line_items": [],
    "transactions": [
      {
        "order_id": 450789469,
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "amount": "2.00",
        "currency": "USD",
        "maximum_refundable": "41.94"
      }
    ],
    "currency": "USD"
  }
}
POST /admin/api/2020-07/orders/{order_id}/refunds.json

Creates a refund. Use the calculate endpoint to produce the transactions to submit.


restock
deprecated

Whether to add the line items back to the store inventory. Use restock_type for refund line items instead.
notify

Whether to send a refund notification to the customer.
note

An optional note attached to a refund.
discrepancy_reason

An optional comment that explains a discrepancy between calculated and actual refund amounts. Used to populate the reason property of the resulting order adjustment object attached to the refund. Valid values: restock, damage, customer, and other.
shipping

Specify how much shipping to refund. It has the following properties:

  • full_refund: Whether to refund all remaining shipping.
  • amount: Set a specific amount to refund for shipping. Takes precedence over full_refund.
refund_line_items

A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:

  • line_item_id: The ID of a line item to refund.
  • quantity: The quantity to refund.
  • restock_type: How this refund line item affects inventory levels. Valid values:
    • no_restock: Refunding these items won't affect inventory.
    • cancel: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.
    • return: The items were already delivered but will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.
  • location_id: The ID of the location where the items should be restocked. This is required when the value of restock_type is return or