Big Commerce Get Refunds

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

We can use this request to track and trace the refunds on the orders and based on this we want to store the refunds if missing in Hemi as per the Refunds send general logic

API Call: GET https://api.bigcommerce.com/stores/{store_hash}/v3/orders/payment_actions/refunds

Docs: https://developer.bigcommerce.com/docs/rest-management/transactions/payment-actions#get-all-refunds

Parameters: created:min - Filter results so they are later than or equal to provided date. Must be in url-encoded RFC 3339 format. e.g. 2020-01-15T01:02:34-01:00 is RFC 3339 format. Url-encoded this will be 2020-01-15T01%3A02%3A34%2B01%3A00

We want to use the last date run table and store the date of the last run of the cron. If we have a record for the cron id we want to use it as created:min - 2 hours. Please note the first run of the cron get all refunds and we are not using any filters.

<v1.2> We need to add couple of specifications because of the item_type “ORDER“. Since Order type refund is not associated with the product we will include the following:

1 First we will insert all other types and always the order type last.

2 If we receive full order cancellation with order type we will just split it across on the possible items.

This way we will cover most of cases except one!

The only cases which we are not able to cover is when we have an order with partial refund with type “ORDER“ and then another partial refund with “PRODUCT“ type. In this case we will receive an error that there is problem with storing the refund id. </v1.2>

BigCommerce are using pagination and based on the meta node we can check how many pages we have in the response and how to filter through the pages. GET https://api.bigcommerce.com/stores/{store_hash}/v3/orders/payment_actions/refunds?page=1&limit=50

Sample Request: GET https://api.bigcommerce.com/stores/m6aov21knis/v3/orders/payment_actions/refunds

Sample Response: Status 200 OK

{
    "data": [
        {
            "id": 1,
            "order_id": 100,
            "user_id": 0,
            "created": "2023-10-16T07:06:53+00:00",
            "reason": "",
            "total_amount": 10,
            "total_tax": 0,
            "uses_merchant_override_values": false,
            "payments": [
                {
                    "id": 1,
                    "provider_id": "cod",
                    "amount": 10,
                    "offline": true,
                    "is_declined": false,
                    "declined_message": ""
                }
            ],
            "items": [
                {
                    "item_type": "ORDER",
                    "item_id": 1,
                    "quantity": null,
                    "requested_amount": 10,
                    "reason": "Customer requested refund"
                }
            ]
        },
        {
            "id": 2,
            "order_id": 100,
            "user_id": 0,
            "created": "2023-10-16T07:07:58+00:00",
            "reason": "",
            "total_amount": 655.94,
            "total_tax": 0,
            "uses_merchant_override_values": false,
            "payments": [
                {
                    "id": 2,
                    "provider_id": "cod",
                    "amount": 655.94,
                    "offline": true,
                    "is_declined": false,
                    "declined_message": ""
                }
            ],
            "items": [
                {
                    "item_type": "ORDER",
                    "item_id": 1,
                    "quantity": null,
                    "requested_amount": 655.94,
                    "reason": "Customer requested refund"
                }
            ]
        },
        {
            "id": 3,
            "order_id": 101,
            "user_id": 0,
            "created": "2023-10-16T12:27:04+00:00",
            "reason": "",
            "total_amount": 12,
            "total_tax": 2,
            "uses_merchant_override_values": false,
            "payments": [
                {
                    "id": 3,
                    "provider_id": "cod",
                    "amount": 12,
                    "offline": true,
                    "is_declined": false,
                    "declined_message": ""
                }
            ],
              "items":[
            {
               "item_type":"GIFT_WRAPPING",
               "item_id":93,
               "quantity":4,
               "requested_amount":null,
               "reason":""
            }
         ],
            "items": [
                {
                    "item_type": "SHIPPING",
                    "item_id": 2,
                    "quantity": null,
                    "requested_amount": 10,
                    "reason": "Customer requested refund"
                }
            ]
        }
    ],
    "meta": {
        "pagination": {
            "total": 3,
            "count": 3,
            "per_page": 50,
            "current_page": 1,
            "total_pages": 1,
            "links": {
                "current": "?page=1&limit=50"
            }
        }
    }
}

Mapping:

Based on the Item_type we will be able to track if this is shipping, item type or gift wrap. Please note if we receive "item_type": "SHIPPING" we want to set Refund Row > Type = Shipping Please note if we receive "item_type": "GIFT_WRAPPING" we want to set Refund Row > Type = Gift Wrap Please note if we receive "item_type": "PRODUCT" we want to set Refund Row > Type = Item If we have case where in the get refund response we receive different item_type from SHIPPING, GIFT_WRAPPING , ORDER or PRODUCT we do NOT want to store the refund but to store an error in Order Error table</v1.1> | | | | item_id | Refund Row > SKU | We want to use theitem_id and map it against the order Product In Order > Item Order Line ID in order to get the SKU.

Please note the item_id value depends on the item_type and here we are receiving different ids: For type = PRODUCT we receive the product id which is our product In Order > Item Order Line ID

For type = ORDER we receive the order id which is our Order > Marketplace ID

For type = SHIPPING we receive the shipping id which is our Orders > Shipping Address Id<v1.1>For type = GIFT_WRAPPING we receive the product id which is our product In Order > Item Order Line ID</v1.1> | | | | quantity | Refund Row > Amount | <v1.1>This is available only for item_type": "PRODUCT" and item_type": "GIFT_WRAPPING"
Based on the quantity we can calculate the Refund Row > Amount</v1.1> Please note if we have "item_type": "SHIPPING" or "item_type": "ORDER" we will have "quantity": null and we want to rely on the requested_amount | | | | requested_amount | Refund Row > Amount | This is available only for item_type": "ORDER" and "item_type": "SHIPPING" This is the amount refunded without VAT.

For "item_type": "SHIPPING" we have to add the VAT and store it as Refund Row > Amount. Please note in order to calculate the refunded shipping price with VAT correctly, we have to calculate it as follows : • If we have case where we have both item_type": "PRODUCT" and "item_type": "SHIPPING" for the same order in the payload, we multiply the quantity (under "item_type": "PRODUCT") with Product In Order > Item Price and then subtract the calculated amount from the total_amount.

• <v1.1>If we have case where we have item_type": "PRODUCT" and "item_type": "GIFT_WRAPPING" and "item_type": "SHIPPING" for the same order in the payload, we multiply the quantity with Product In Order > Item Price for the item_type": "PRODUCT" and we multiply the quantity with Product In Order > Gift Wrap Cost for the item_type": "GIFT_WRAPPING" and then subtract the calculated amount from the total_amount. Same will be the case if we have only "item_type": "GIFT_WRAPPING" and "item_type": "SHIPPING" </v1.1> • If we have a case where we have both "item_type": "ORDER" and "item_type": "SHIPPING" for the same order in the payload we just subtract the requested_amount (under "item_type": "ORDER") from the total_amount since we will have "quantity": null • If we have a case where we have <v1.1>all 4 item_types for the same order we just combine all of the above.</v1.1> After we have calculated how much is the shipping amount for the entire refund we have to decide for which SKU to store it in Hemi. We should always begin from the Product In Order with the lowest ID checking how much Product In Order > Item Shipping Cost is available and unrefunded (completed refunds only) and continue to the next Product in Order only when the full Product In Order > Item Shipping Cost is refunded for this one.

For "item_type": "ORDER" we DO NOT have to add the VAT and store it as Refund Row > Amount directly. | | | | reason | N/A | |

The id is a unique refund ID which we can use to make sure we are not duplicating refunds on the orders.