Refund
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:
- a record of money returned to the customer
- the line items included in the refund, along with restocking instructions
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:
- GET /admin/api/2020-01/orders/{order_id}/refunds.json Retrieves a list of refunds for an order
- GET /admin/api/2020-01/orders/{order_id}/refunds/{refund_id}.json Retrieves a specific refund
- POST /admin/api/2020-01/orders/{order_id}/refunds/calculate.json Calculates a refund
- POST /admin/api/2020-01/orders/{order_id}/refunds.json Creates a refund
Refund properties
created_at
read-only |
The date and time (ISO 8601 format) when the refund was created. |
id
read-only |
The unique identifier for the refund. |
note |
An optional note attached to a refund. |
order_adjustments
read-only |
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:
|
processed_at |
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 |
A list of refunded line items. Each entry has the following properties:
|
restock
deprecated |
Whether to add the line items back to the store's inventory. Provide a |
transactions |
A list of transactions involved in the refund. For more information, see the Transaction resource. |
user_id |
The unique identifier of the user who performed the refund. |
Endpoints
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-01/orders/450789469/refunds.json
View Response
HTTP/1.1 200 OK
{
"refunds": [
{
"id": 509562969,
"order_id": 450789469,
"created_at": "2021-01-01T14:22:39-05:00",
"note": "it broke during shipping",
"user_id": 799407056,
"processed_at": "2021-01-01T14:22:39-05:00",
"restock": true,
"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"
}
}
}
],
"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"
}
}
}
],
"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,
"error_code": null,
"source_name": "web",
"receipt": {},
"amount": "209.00",
"currency": "USD",
"admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
}
],
"order_adjustments": []
}
]
}
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-01/orders/450789469/refunds/509562969.json
View Response
HTTP/1.1 200 OK
{
"refund": {
"id": 509562969,
"order_id": 450789469,
"created_at": "2021-01-01T14:22:39-05:00",
"note": "it broke during shipping",
"user_id": 799407056,
"processed_at": "2021-01-01T14:22:39-05:00",
"restock": true,
"duties": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"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,
"error_code": null,
"source_name": "web",
"receipt": {},
"amount": "209.00",
"currency": "USD",
"admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
}
],
"order_adjustments": []
}
}
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:
|
refund_line_items
|
A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:
|
currency
|
The three-letter code (ISO 4217 format) for the
currency used for the refund. Note: Required whenever the shipping |
Calculate the refund without specifying currency
POST /admin/api/2020-01/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": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"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-01/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": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"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-01/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": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"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"
}
}
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 |
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 |
shipping
|
Specify how much shipping to refund. It has the following properties:
|
refund_line_items
|
A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:
|
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-01/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": 929361466,
"order_id": 450789469,
"created_at": "2021-01-01T14:33:06-05:00",
"note": "wrong size",
"user_id": null,
"processed_at": "2021-01-01T14:33:06-05:00",
"restock": true,
"duties": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"admin_graphql_api_id": "gid://shopify/Refund/929361466",
"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": 1072844688,
"order_id": 450789469,
"kind": "refund",
"gateway": "bogus",
"status": "success",
"message": "Bogus Gateway: Forced success",
"created_at": "2021-01-01T14:33:05-05:00",
"test": true,
"authorization": null,
"location_id": null,
"user_id": null,
"parent_id": 801038806,
"processed_at": "2021-01-01T14:33:05-05:00",
"device_id": null,
"error_code": null,
"source_name": "755357713",
"receipt": {},
"amount": "41.94",
"currency": "USD",
"admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844688"
}
],
"order_adjustments": []
}
}
Refund a specific amount of shipping
POST /admin/api/2020-01/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": 929361467,
"order_id": 450789469,
"created_at": "2021-01-01T14:33:08-05:00",
"note": null,
"user_id": null,
"processed_at": "2021-01-01T14:33:08-05:00",
"restock": false,
"duties": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"admin_graphql_api_id": "gid://shopify/Refund/929361467",
"refund_line_items": [],
"transactions": [
{
"id": 1072844689,
"order_id": 450789469,
"kind": "refund",
"gateway": "bogus",
"status": "success",
"message": "Bogus Gateway: Forced success",
"created_at": "2021-01-01T14:33:08-05:00",
"test": true,
"authorization": null,
"location_id": null,
"user_id": null,
"parent_id": 801038806,
"processed_at": "2021-01-01T14:33:08-05:00",
"device_id": null,
"error_code": null,
"source_name": "755357713",
"receipt": {},
"amount": "5.00",
"currency": "USD",
"admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844689"
}
],
"order_adjustments": [
{
"id": 1030976844,
"order_id": 450789469,
"refund_id": 929361467,
"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"
}
}
}
]
}
}
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:
- a record of money returned to the customer
- the line items included in the refund, along with restocking instructions
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:
- GET /admin/api/2020-04/orders/{order_id}/refunds.json Retrieves a list of refunds for an order
- GET /admin/api/2020-04/orders/{order_id}/refunds/{refund_id}.json Retrieves a specific refund
- POST /admin/api/2020-04/orders/{order_id}/refunds/calculate.json Calculates a refund
- POST /admin/api/2020-04/orders/{order_id}/refunds.json Creates a refund
Refund properties
created_at
read-only |
The date and time (ISO 8601 format) when the refund was created. |
duties
read-only |
A list of duties that have been returned as part of the refund. |
id
read-only |
The unique identifier for the refund. |
note |
An optional note attached to a refund. |
order_adjustments
read-only |
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:
|
processed_at |
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 |
A list of refunded line items. Each entry has the following properties:
|
restock
deprecated |
Whether to add the line items back to the store's inventory. Provide a |
transactions |
A list of transactions involved in the refund. For more information, see the Transaction resource. |
user_id |
The unique identifier of the user who performed the refund. |
Endpoints
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-04/orders/450789469/refunds.json
View Response
HTTP/1.1 200 OK
{
"refunds": [
{
"id": 509562969,
"order_id": 450789469,
"created_at": "2021-01-01T14:22:39-05:00",
"note": "it broke during shipping",
"user_id": 799407056,
"processed_at": "2021-01-01T14:22:39-05:00",
"restock": true,
"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"
}
}
}
],
"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"
}
}
}
],
"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,
"error_code": null,
"source_name": "web",
"receipt": {},
"amount": "209.00",
"currency": "USD",
"admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
}
],
"order_adjustments": []
}
]
}
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-04/orders/450789469/refunds/509562969.json
View Response
HTTP/1.1 200 OK
{
"refund": {
"id": 509562969,
"order_id": 450789469,
"created_at": "2021-01-01T14:22:39-05:00",
"note": "it broke during shipping",
"user_id": 799407056,
"processed_at": "2021-01-01T14:22:39-05:00",
"restock": true,
"duties": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"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,
"error_code": null,
"source_name": "web",
"receipt": {},
"amount": "209.00",
"currency": "USD",
"admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
}
],
"order_adjustments": []
}
}
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:
|
refund_line_items
|
A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:
|
currency
|
The three-letter code (ISO 4217 format) for the
currency used for the refund. Note: Required whenever the shipping |
Calculate the refund without specifying currency
POST /admin/api/2020-04/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": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"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-04/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": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"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-04/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": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"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"
}
}
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 |
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 |
shipping
|
Specify how much shipping to refund. It has the following properties:
|
refund_line_items
|
A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:
|
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-04/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": 929361466,
"order_id": 450789469,
"created_at": "2021-01-01T14:33:06-05:00",
"note": "wrong size",
"user_id": null,
"processed_at": "2021-01-01T14:33:06-05:00",
"restock": true,
"duties": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"admin_graphql_api_id": "gid://shopify/Refund/929361466",
"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": 1072844688,
"order_id": 450789469,
"kind": "refund",
"gateway": "bogus",
"status": "success",
"message": "Bogus Gateway: Forced success",
"created_at": "2021-01-01T14:33:05-05:00",
"test": true,
"authorization": null,
"location_id": null,
"user_id": null,
"parent_id": 801038806,
"processed_at": "2021-01-01T14:33:05-05:00",
"device_id": null,
"error_code": null,
"source_name": "755357713",
"receipt": {},
"amount": "41.94",
"currency": "USD",
"admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844688"
}
],
"order_adjustments": []
}
}
Refund a specific amount of shipping
POST /admin/api/2020-04/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": 929361467,
"order_id": 450789469,
"created_at": "2021-01-01T14:33:08-05:00",
"note": null,
"user_id": null,
"processed_at": "2021-01-01T14:33:08-05:00",
"restock": false,
"duties": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"admin_graphql_api_id": "gid://shopify/Refund/929361467",
"refund_line_items": [],
"transactions": [
{
"id": 1072844689,
"order_id": 450789469,
"kind": "refund",
"gateway": "bogus",
"status": "success",
"message": "Bogus Gateway: Forced success",
"created_at": "2021-01-01T14:33:08-05:00",
"test": true,
"authorization": null,
"location_id": null,
"user_id": null,
"parent_id": 801038806,
"processed_at": "2021-01-01T14:33:08-05:00",
"device_id": null,
"error_code": null,
"source_name": "755357713",
"receipt": {},
"amount": "5.00",
"currency": "USD",
"admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844689"
}
],
"order_adjustments": [
{
"id": 1030976844,
"order_id": 450789469,
"refund_id": 929361467,
"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"
}
}
}
]
}
}
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:
- a record of money returned to the customer
- the line items included in the refund, along with restocking instructions
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:
- GET /admin/api/2020-07/orders/{order_id}/refunds.json Retrieves a list of refunds for an order
- GET /admin/api/2020-07/orders/{order_id}/refunds/{refund_id}.json Retrieves a specific refund
- POST /admin/api/2020-07/orders/{order_id}/refunds/calculate.json Calculates a refund
- POST /admin/api/2020-07/orders/{order_id}/refunds.json Creates a refund
Refund properties
created_at
read-only |
The date and time (ISO 8601 format) when the refund was created. |
duties
read-only |
A list of duties that have been returned as part of the refund. |
id
read-only |
The unique identifier for the refund. |
note |
An optional note attached to a refund. |
order_adjustments
read-only |
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:
|
processed_at |
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 |
A list of refunded line items. Each entry has the following properties:
|
restock
deprecated |
Whether to add the line items back to the store's inventory. Provide a |
transactions |
A list of transactions involved in the refund. For more information, see the Transaction resource. |
user_id |
The unique identifier of the user who performed the refund. |
Endpoints
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": "2021-01-01T14:22:39-05:00",
"note": "it broke during shipping",
"user_id": 799407056,
"processed_at": "2021-01-01T14:22:39-05:00",
"restock": true,
"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"
}
}
}
],
"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"
}
}
}
],
"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,
"error_code": null,
"source_name": "web",
"receipt": {},
"amount": "209.00",
"currency": "USD",
"admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
}
],
"order_adjustments": []
}
]
}
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": "2021-01-01T14:22:39-05:00",
"note": "it broke during shipping",
"user_id": 799407056,
"processed_at": "2021-01-01T14:22:39-05:00",
"restock": true,
"duties": [],
"total_duties_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"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"