API2Cart allows you to manage refunds for orders across multiple eCommerce platforms using a unified API. This guide explains how to create partial and full refunds, check their statuses, and access related data.

Method order.refund.add

This method allows you to initiate a refund for an order.

Parameters:

  • order_id (required) - ID of the order you want to refund.

  • items - List of products to refund:

    • order_product_id (required) - product identifier in the order. You can find it in the response of the order.info or order.list methods in the order_products->order_product_id field.

    • quantity (required) - quantity of products for refund (for partial refund).

    • price - price per one product for refund. Must be ≤ the initial price.

    • If items not specified, a full refund is created.

  • total_price - The full amount that will be refunded. The value must be ≤ the payment amount.

  • shipping_price - Amount of shipping to refund. The value must be ≤ the initial shipping price.

  • fee_price - Additional fees to refund. The value must be ≤ the initial fee amount.

  • message - Comment to the refund. Usually contains the reason for the refund.

  • item_restock - Determines whether inventory levels need to be updated for returned products.

  • is_online - Initiate a refund in the payment system, if supported.

You can find all information about shipping price, payment amounts, fees, etc in the response of the order.info or order.list methods in the totals field.

Please note that some options may not be supported for a specific platform, so check if the platform you are working with supports specific options by selecting a specific platform in our documentation.

A refund can also be created using an RMA. More on that here.

Method order.info

Use this method to check the refund status for a specific order.

Useful Fields in the Response

  • refunds - Contains a list of all refunds associated with this order.

  • status->refund_info - Summary of refund amounts:

    • total_refunded - Total refunded amount.

    • shipping, fee, tax - Refunded components as separate fields.

    • refunded_items - Breakdown of refunded products, quantities, and amounts.

Method order.list

Can be useful when you need to get a list of orders for which refunds were created. Most platforms support the financial_status filter, which allows you to filter orders that have been refunded or partially refunded. To find out which financial statuses are supported by the platform, you can use the order.financial_status.list method or you can get a list of supported financial statuses by passing any clearly invalid value for financial_status. The error message will include the list of supported sorting fields:

{
    "return_code": 109,
    "return_message": "Parameter 'financial_status' is not valid. The required type of parameter is enum. One of the following values are allowed: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided.",
    "result": {}
}

Example Scenario

  1. The customer wants to return 2 of 5 items with order product ID = 14971781972196 from order ID = 6192369107172

  2. You call order.refund.add with body: 

    {
    "order_id": "1234",
    "items": [
        {
            "order_product_id": "1",
            "quantity": 2
        }
    ],
    "message": "Two units were broken!"
}

  3. You receive a response with the refund ID: 

    {
    "return_code": 0,
    "return_message": "",
    "result": {
        "refund_id": "921447923940",
        "additional_refund_ids": null
    }
}

  4. Use order.info?order_id=921447923940 to view the result: 

    {
    "result": {
        "status": {
            "refund_info": {
                "shipping": 0,
                "fee": 0,
                "tax": 0,
                "total_refunded": 111.1,
                "time": {
                    "value": "2025-06-12T13:08:39+0300",
                    "format": "Y-m-d\\TH:i:sO"
                },
                "comment": "Two units were broken!",
                "refunded_items": [
                    {
                        "product_id": "8624342761700",
                        "variant_id": null,
                        "order_product_id": "14971781972196",
                        "qty": 2,
                        "refund": 111.1
                    }
                ]
            }
        },
        "refunds": [
            {
                "id": "921447923940",
                "shipping": 0,
                "fee": 0,
                "tax": 0,
                "total": 111.1,
                "modified_time": {
                    "value": "2025-06-12T13:08:39+0300",
                    "format": "Y-m-d\\TH:i:sO"
                },
                "comment": "Two units were broken!",
                "items": [
                    {
                        "product_id": "8624342761700",
                        "variant_id": null,
                        "order_product_id": "14971781972196",
                        "qty": 2,
                        "refund": 111.1,
                        "additional_fields": {
                            "restocked": true
                        }
                    }
                ]
            }
        ],
        "additional_fields": {
            "financial_status": "partially_refunded"
        }
    }
}

  5. If needed, you can also include shipping amount or other values.