Correct way to calculation refunds of an order?

Retired Boards Appdev Customers Discounts And Orders
1

I’m an app developer and we’re now calculating refunds on order basis for our users. Noticed there are three fields related in “order.refunds”:

  • refund_line_items: I assume items here are fully refunded of their sold price & tax. For example if I see an item with subtotal 19.95 and tax 1.65, I assume the refund is 21.6.

  • order_adjustment: from the docs I see this includes “shipping cost” and “differences between calculated and actual refund amounts”. Shipping cost is straightforward, so like if there’s a $10 cost I’ll add $10 to the total refund amount. For the 2nd kind of entries I haven’t found an example yet, but I assume I’ll need to subtract the amount of it from the total refund amount.

  • transactions: this looks somehow duplicate. Is this the actual refund made to the buyer, like total of the above? I also see gift card entries in this field, should I ignore it when calculating?

1 Like
2

Hi @kenxu0927 ,

It’s not clear what your question is. The correct way is how it’s described in the docs and what’s been proven in the real world. Why are you calculating your refunds when there’s an API for that?

Calculations API

POST /admin/api/2020-07/orders/450789469/refunds/calculate.json

This is straightforward, you’re going to send Calculations API the items you want to refund. An example of such a request below:

{
  "refund": {
    "shipping": {
      "full_refund": true
    },
    "refund_line_items": [
      {
        "line_item_id": 518995019,
        "quantity": 1,
        "restock_type": "no_restock"
      }
    ]
  }
}

You take the transactions response from Calculations and POST to Refunds endpoint.

Regards,

Sam Bazargan - Owner

3

Hi Sam,

My question is, based on the “refunds” field of an order object (returned from the GET /orders/{id}.json endpoint), how could I get the “total refund amount” of this order. We are not making refunds on behalf of our users (the sellers) but extracting the total refund amount from the order object. I checked refund calculation endpoint and looks like it returns an almost identical format to order.refunds, not a total amount.

One example with real data is like:

[
  {
        "id": 661666988145,
        "order_id": 2415770468465,
        "refund_line_items": [
            {
                "id": 164205625457,
                "line_item_id": 5145381142641,
                "quantity": 1,
                "restock_type": "cancel",
                "location_id": 35927359601,
                "subtotal": "39.90",
                "total_tax": "4.27",
            }
        ],
        "transactions": [],
        "order_adjustments": []
    },
    {
        "id": 668569698417,
        "order_id": 2415770468465,
        "refund_line_items": [
            {
                "id": 171796693105,
                "line_item_id": 5145381109873,
                "quantity": 2,
                "restock_type": "cancel",
                "location_id": 35989192817,
                "subtotal": "139.80",
                "total_tax": "14.97",
            },
            {
                "id": 171796725873,
                "line_item_id": 5145381142641,
                "quantity": 1,
                "restock_type": "cancel",
                "location_id": 35989192817,
                "subtotal": "39.90",
                "total_tax": "4.28",
            }
        ],
        "transactions": [
            {
                "id": 3094383951985,
                "order_id": 2415770468465,
                "kind": "refund",
                "gateway": "gift_card",
                "status": "success",
                "message": null,
                "created_at": "2020-07-07T21:11:19+02:00",
                "test": false,
                "authorization": null,
                "location_id": null,
                "user_id": null,
                "parent_id": 2975174230129,
                "processed_at": "2020-07-07T21:11:19+02:00",
                "device_id": null,
                "receipt": {
                    "gift_card_id": 424086896753,
                    "gift_card_last_characters": "2h6c"
                },
                "error_code": null,
                "source_name": "web",
                "amount": "100.00",
                "currency": "SEK",
                "admin_graphql_api_id": "gid://shopify/OrderTransaction/3094383951985"
            },
            {
                "id": 3094383984753,
                "order_id": 2415770468465,
                "kind": "void",
                "gateway": "Swish",
                "status": "success",
                "message": "Marked the Swish payment as voided",
                "created_at": "2020-07-07T21:11:20+02:00",
                "test": false,
                "authorization": null,
                "location_id": null,
                "user_id": null,
                "parent_id": 2975174295665,
                "processed_at": "2020-07-07T21:11:20+02:00",
                "device_id": null,
                "receipt": {},
                "error_code": null,
                "source_name": "web",
                "amount": "0.00",
                "currency": "SEK",
                "admin_graphql_api_id": "gid://shopify/OrderTransaction/3094383984753"
            }
        ],
        "order_adjustments": [
            {
                "id": 102158565489,
                "order_id": 2415770468465,
                "refund_id": 668569698417,
                "amount": "-79.46",
                "tax_amount": "-9.54",
                "kind": "shipping_refund",
                "reason": "Shipping refund",
                "amount_set": {
                    "shop_money": {
                        "amount": "-79.46",
                        "currency_code": "SEK"
                    },
                    "presentment_money": {
                        "amount": "-79.46",
                        "currency_code": "SEK"
                    }
                },
                "tax_amount_set": {
                    "shop_money": {
                        "amount": "-9.54",
                        "currency_code": "SEK"
                    },
                    "presentment_money": {
                        "amount": "-9.54",
                        "currency_code": "SEK"
                    }
                }
            }
        ]
    }
]

Should I use the line item totals (39.9+4.27)*1 + (139.8+14.97)*2 + (39.9+4.28)*1 plus shipping (79.46+9.54) as the final amount, or should I use another way to calculate? Thanks!

4

@kenxu0927 ,

No you would not multiply the subtotals with the quantity. Is it not feasible to just cycle through only transactions adding the amount field? That way you know that’s what’s actually been credited to customer.

Regards,

Sam Bazargan - Owner

1 Like
5

Yeah sorry I made a mistake in using subtotals. So if go back to the above example… does it mean the refund is simply a gift card of 100 SEK? I was just confused about the number since those in other fields don’t add up to 100.

6

There’s nothing in the docs that would imply an order_adjustment results in a transaction. So your answer would be yes only the gift card amount was credited to the customer.

Interesting enough order_adjustments are read only and can be created automatically by Shopify to account for discrepancies.

Regards,

Sam Bazargan - Owner

7

I have exact same requirement! Would you please provide the XSLT function to total the amounts under Order-Refunds section for an Order? Will it be sum(Amount) ?

8

my Order API is returning

{
“refunds”: [
{
“id”: 841191751747,
“order_id”: 4296396931139,
“created_at”: “2022-06-22T02:08:41-07:00”,
“note”: “Partial refund of RMA #35579824 funded by Instant Refunds Voucher which in turn was funded by RMA #34067426 (processed by Returnly)”,
“user_id”: null,
“processed_at”: “2022-06-22T02:08:41-07: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/841191751747”,
“refund_line_items”: ,
“transactions”: [
{
“id”: 5522486132803,
“order_id”: 4296396931139,
“kind”: “refund”,
“gateway”: “authorize_net”,
“status”: “success”,
“message”: “This transaction has been approved”,
“created_at”: “2022-06-22T02:08:40-07:00”,
“test”: false,
“authorization”: “63779086171#4605#refund”,
“location_id”: null,
“user_id”: null,
“parent_id”: 5314113929283,
“processed_at”: “2022-06-22T02:08:40-07:00”,
“device_id”: null,
“error_code”: null,
“source_name”: “352363”,
“payment_details”: {
“credit_card_bin”: “555753”,
“avs_result_code”: “Y”,
“cvv_result_code”: “M”,
“credit_card_number”: “•••• •••• •••• 4605”,
“credit_card_company”: “Mastercard”
},
“receipt”: {
“action”: “refund”,
“response_code”: 1,
“response_reason_code”: “1”,
“response_reason_text”: “This transaction has been approved”,
“avs_result_code”: “P”,
“transaction_id”: “63779086171”,
“card_code”: null,
“authorization_code”: null,
“cardholder_authentication_code”: null,
“account_number”: “4605”,
“test_request”: “0”,
“full_response_code”: “I00001”,
“network_trans_id”: null
},
“amount”: “57.32”,
“currency”: “USD”,
“admin_graphql_api_id”: “gid://shopify/OrderTransaction/5522486132803”
}
],
“order_adjustments”: [
{
“id”: 198878724163,
“order_id”: 4296396931139,
“refund_id”: 841191751747,
“amount”: “-57.32”,
“tax_amount”: “0.00”,
“kind”: “refund_discrepancy”,
“reason”: “Refund discrepancy”,
“amount_set”: {
“shop_money”: {
“amount”: “-57.32”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “-57.32”,
“currency_code”: “USD”
}
},
“tax_amount_set”: {
“shop_money”: {
“amount”: “0.00”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “0.00”,
“currency_code”: “USD”
}
}
}
]
},
{
“id”: 842744234051,
“order_id”: 4296396931139,
“created_at”: “2022-07-10T17:26:18-07:00”,
“note”: "110353500-44 : Too Small – processed by Returnly for RMA #34067426 – refund value applied to ",
“user_id”: null,
“processed_at”: “2022-07-10T17:26:18-07: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/842744234051”,
“refund_line_items”: [
{
“id”: 345427836995,
“quantity”: 1,
“line_item_id”: 10994648580163,
“location_id”: 61507338307,
“restock_type”: “no_restock”,
“subtotal”: 53.95,
“total_tax”: 3.37,
“subtotal_set”: {
“shop_money”: {
“amount”: “53.95”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “53.95”,
“currency_code”: “USD”
}
},
“total_tax_set”: {
“shop_money”: {
“amount”: “3.37”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “3.37”,
“currency_code”: “USD”
}
},
“line_item”: {
“id”: 10994648580163,
“variant_id”: 31219018825795,
“title”: “Wally Sox Funk”,
“quantity”: 1,
“sku”: “110353500-44”,
“variant_title”: “11/44 / Ash”,
“vendor”: “Hey Dude Shoes”,
“fulfillment_service”: “manual”,
“product_id”: 3952150347843,
“requires_shipping”: true,
“taxable”: true,
“gift_card”: false,
“tax_code”: “PC040144”,
“name”: “Wally Sox Funk - 11/44 / Ash”,
“variant_inventory_management”: null,
“properties”: ,
“product_exists”: true,
“fulfillable_quantity”: 0,
“grams”: 680,
“price”: “59.95”,
“total_discount”: “0.00”,
“fulfillment_status”: “fulfilled”,
“pre_tax_price”: “53.95”,
“price_set”: {
“shop_money”: {
“amount”: “59.95”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “59.95”,
“currency_code”: “USD”
}
},
“pre_tax_price_set”: {
“shop_money”: {
“amount”: “53.95”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “53.95”,
“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”: “6.00”,
“discount_application_index”: 0,
“amount_set”: {
“shop_money”: {
“amount”: “6.00”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “6.00”,
“currency_code”: “USD”
}
}
}
],
“duties”: ,
“admin_graphql_api_id”: “gid://shopify/LineItem/10994648580163”,
“tax_lines”: [
{
“title”: “TX STATE TAX”,
“price”: “3.37”,
“rate”: 0.0625,
“channel_liable”: false,
“price_set”: {
“shop_money”: {
“amount”: “3.37”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “3.37”,
“currency_code”: “USD”
}
}
}
],
“origin_location”: {
“id”: 3055704080451,
“country_code”: “US”,
“province_code”: “CA”,
“name”: “Hey Dude Shoes”,
“address1”: “110 Sutter Street”,
“address2”: “9th Floor”,
“city”: “San Francisco”,
“zip”: “94104”
},
“destination_location”: {
“id”: 3228654960707,
“country_code”: “US”,
“province_code”: “TX”,
“name”: “Andrew Pettigrew”,
“address1”: “793 vz county road 3403”,
“address2”: “”,
“city”: "Wills point ",
“zip”: “75169”
}
}
}
],
“transactions”: ,
“order_adjustments”: [
{
“id”: 199796621379,
“order_id”: 4296396931139,
“refund_id”: 842744234051,
“amount”: “57.32”,
“tax_amount”: “0.00”,
“kind”: “refund_discrepancy”,
“reason”: “Refund discrepancy”,
“amount_set”: {
“shop_money”: {
“amount”: “57.32”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “57.32”,
“currency_code”: “USD”
}
},
“tax_amount_set”: {
“shop_money”: {
“amount”: “0.00”,
“currency_code”: “USD”
},
“presentment_money”: {
“amount”: “0.00”,
“currency_code”: “USD”
}
}
}
]
}
]
}

Question: Do I just do sum (ns27:refunds/ns27:transactions/ns27:amount ) to get total refund amount for the order ?