Refund

A refund is a record of the money returned to the customer, and/or the return of any items on an order which may or may not have been restocked.

What can you 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
{ "created_at" : "2008-01-10T11:00:00-05:00" }

The date and time when the refund was created. The API returns this value in ISO 8601 format.

id
{ "id" : 92738740 }

The unique numeric identifier for the refund. This one is used for API purposes.

note
{ "note" : "Item was damaged during shipping" }

The optional note attached to a refund.

refund_line_items
{ "id" : 209341123 }
{ "line_item" : {} }
{ "line_item_id" : 128323456 }
{ "quantity" : 2 }

Details about one returned/refunded item. It has the following properties:

  • id: The unique identifier of the refund line item.
  • line_item: The single line item being returned.
  • line_item_id: The id of the related line item.
  • quantity: The quantity of the associated line item that was returned.

restock
{ "restock" : true }

Whether or not the line items were added back to the store inventory.

transactions

The list of transactions involved in the refund.

user_id
{ "user_id" : 238478920 }

The unique identifier of the user who performed the refund.

Endpoints

GET /admin/orders/450789469/refunds.json

Retrieve a list of Refunds for an Order

fields

Comma-separated list of fields to include in the response

Get all refunds from a specific order

GET /admin/orders/#{id}/refunds.json
View Response
HTTP/1.1 200 OK
{
  "refunds": [
    {
      "id": 509562969,
      "order_id": 450789469,
      "created_at": "2016-11-09T13:52:05-05:00",
      "note": "it broke during shipping",
      "restock": true,
      "user_id": 799407056,
      "refund_line_items": [
        {
          "id": 104689539,
          "quantity": 1,
          "line_item_id": 703073504,
          "subtotal": 195.67,
          "total_tax": 3.98,
          "line_item": {
            "id": 703073504,
            "variant_id": 457924702,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "price": "199.00",
            "grams": 200,
            "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,
            "total_discount": "0.00",
            "fulfillment_status": null,
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06
              }
            ]
          }
        },
        {
          "id": 709875399,
          "quantity": 1,
          "line_item_id": 466157049,
          "subtotal": 195.66,
          "total_tax": 3.98,
          "line_item": {
            "id": 466157049,
            "variant_id": 39072856,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "price": "199.00",
            "grams": 200,
            "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,
            "total_discount": "0.00",
            "fulfillment_status": null,
            "tax_lines": [
              {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06
              }
            ]
          }
        }
      ],
      "transactions": [
        {
          "id": 179259969,
          "order_id": 450789469,
          "amount": "209.00",
          "kind": "refund",
          "gateway": "bogus",
          "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": null,
          "device_id": null,
          "receipt": {},
          "error_code": null,
          "source_name": "web"
        }
      ],
      "order_adjustments": [
      ]
    }
  ]
}
GET /admin/orders/450789469/refunds/509562969.json

Retrieve a specific refund

fields

Comma-separated list of fields to include in the response

Get a representation of a single refund

GET /admin/orders/#{id}/refunds/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "refund": {
    "id": 509562969,
    "order_id": 450789469,
    "created_at": "2016-11-09T13:52:05-05:00",
    "note": "it broke during shipping",
    "restock": true,
    "user_id": 799407056,
    "refund_line_items": [
      {
        "id": 104689539,
        "quantity": 1,
        "line_item_id": 703073504,
        "subtotal": 195.67,
        "total_tax": 3.98,
        "line_item": {
          "id": 703073504,
          "variant_id": 457924702,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "price": "199.00",
          "grams": 200,
          "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,
          "total_discount": "0.00",
          "fulfillment_status": null,
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06
            }
          ]
        }
      },
      {
        "id": 709875399,
        "quantity": 1,
        "line_item_id": 466157049,
        "subtotal": 195.66,
        "total_tax": 3.98,
        "line_item": {
          "id": 466157049,
          "variant_id": 39072856,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "price": "199.00",
          "grams": 200,
          "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,
          "total_discount": "0.00",
          "fulfillment_status": null,
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 179259969,
        "order_id": 450789469,
        "amount": "209.00",
        "kind": "refund",
        "gateway": "bogus",
        "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": null,
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "web"
      }
    ],
    "order_adjustments": [
    ]
  }
}
POST /admin/orders/450789469/refunds/calculate.json

Calculate refund transactions based on line items and shipping. The returned response can be used to create a Refund. Note that returned transactions are of the kind "suggested_refund", which must to be changed to "refund" in order for them to be accepted.

shipping

Object to specify how much shipping to refund

  • full_refund - Boolean, set to true to refund all remaining shipping
  • amount - Set specific amount of shipping to refund. Takes precedence over full_refund.
refund_line_items

Array of line item IDs and quantities to refund

Calculate a refund for a partial amount of shipping

POST /admin/orders/#{id}/refunds/calculate.json
{
  "refund": {
    "shipping": {
      "amount": 2.0
    }
  }
}
View Response
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "2.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "refund_line_items": [
    ],
    "transactions": [
      {
        "order_id": 450789469,
        "amount": "2.00",
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "maximum_refundable": "250.94"
      }
    ]
  }
}

Calculate a refund for a line item and shipping

POST /admin/orders/#{id}/refunds/calculate.json
{
  "refund": {
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1
      }
    ]
  }
}
View Response
HTTP/1.1 200 OK
{
  "refund": {
    "shipping": {
      "amount": "5.00",
      "tax": "0.00",
      "maximum_refundable": "5.00"
    },
    "refund_line_items": [
      {
        "quantity": 1,
        "line_item_id": 518995019,
        "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,
        "amount": "204.65",
        "kind": "suggested_refund",
        "gateway": "bogus",
        "parent_id": 801038806,
        "maximum_refundable": "250.94"
      }
    ]
  }
}
POST /admin/orders/450789469/refunds.json

Create a Refund for an existing Order. It is highly suggested that you use the calculate endpoint to produce the transactions to submit.

restock

Boolean, whether or not to add the line items back to the store inventory.

notify

Boolean, set to <code>true</code> to send a refund notification to the customer.

note

An optional comment attached to a refund.

discrepancy_reason

An optional comment, used if there is a discrepancy between calculated and actual refund amounts (one of: restock, damage, customer, other)

shipping

Object to specify how much shipping to refund

  • full_refund - Boolean, set to true to refund all remaining shipping
  • amount - Set specific amount of shipping to refund. Takes precedence over full_refund.
refund_line_items

Array of line item IDs and quantities to refund

transactions

Array of transactions to process as refunds

Create a new refund for an order

POST /admin/orders/#{id}/refunds.json
{
  "refund": {
    "restock": true,
    "notify": true,
    "note": "wrong size",
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1
      }
    ],
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 199.65,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
View Response
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361464,
    "order_id": 450789469,
    "created_at": "2016-11-09T13:53:19-05:00",
    "note": "wrong size",
    "restock": true,
    "user_id": 0,
    "refund_line_items": [
      {
        "id": 1058498311,
        "quantity": 1,
        "line_item_id": 518995019,
        "subtotal": 195.67,
        "total_tax": 3.98,
        "line_item": {
          "id": 518995019,
          "variant_id": 49148385,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "price": "199.00",
          "grams": 200,
          "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": 0,
          "total_discount": "0.00",
          "fulfillment_status": null,
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06
            }
          ]
        }
      }
    ],
    "transactions": [
      {
        "id": 1068278485,
        "order_id": 450789469,
        "amount": "199.65",
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2016-11-09T13:53:19-05:00",
        "test": true,
        "authorization": null,
        "currency": "USD",
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713"
      }
    ],
    "order_adjustments": [
    ]
  }
}

Refunding a specific amount of shipping

POST /admin/orders/#{id}/refunds.json
{
  "refund": {
    "shipping": {
      "amount": 5.0
    },
    "transactions": [
      {
        "parent_id": 801038806,
        "amount": 5.0,
        "kind": "refund",
        "gateway": "bogus"
      }
    ]
  }
}
View Response
HTTP/1.1 201 Created
{
  "refund": {
    "id": 929361465,
    "order_id": 450789469,
    "created_at": "2016-11-09T13:53:21-05:00",
    "note": null,
    "restock": null,
    "user_id": 0,
    "refund_line_items": [
    ],
    "transactions": [
      {
        "id": 1068278486,
        "order_id": 450789469,
        "amount": "5.00",
        "kind": "refund",
        "gateway": "bogus",
        "status": "success",
        "message": "Bogus Gateway: Forced success",
        "created_at": "2016-11-09T13:53:21-05:00",
        "test": true,
        "authorization": null,
        "currency": "USD",
        "location_id": null,
        "user_id": null,
        "parent_id": 801038806,
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "755357713"
      }
    ],
    "order_adjustments": [
      {
        "id": 1030976843,
        "order_id": 450789469,
        "refund_id": 929361465,
        "amount": "-5.00",
        "tax_amount": "0.00",
        "kind": "shipping_refund",
        "reason": "Shipping refund"
      }
    ]
  }
}