Skip to main content
Deprecation Notice: The Refunds endpoint is maintained for backward compatibility. New integrations should use the /v4/ecommerce/transactions endpoint with type=refund filter which provides:
  • Unified transaction model for payments, refunds, and chargebacks
  • Complete payment method and gateway information
  • Linked original transaction references

​
Migration Guide

V3/Legacy EndpointV4 Recommended Endpoint
GET /ecommerce/refundsGET /ecommerce/transactions?type=refund
GET /ecommerce/refunds/:idGET /ecommerce/transactions/:id

​
Key Differences

The unified Transactions model includes:
  • Transaction Types: payment, refund, chargeback, adjustment, fee
  • Payment Method Details: Card, bank_transfer, PayPal, Apple Pay, Google Pay, etc.
  • Gateway Information: Payment processor name and gateway transaction ID
  • Original Transaction Link: For refunds, reference to the original payment
  • Reason Codes: Standardized reasons for refunds (customer_request, fraud, etc.) - Note: customer_request refers to contact request

​
Refunds (Legacy)

The Refunds model provides:
  • Basic refund information tied to orders
  • Limited payment method details
  • Separate from payment records

​
Example Migration

Legacy Refunds Request: 
GET /v4/ecommerce/refunds?order_id=ord_123456
New Transactions Request: 
GET /v4/ecommerce/transactions?type=refund&order_id=ord_123456
New Transactions Response: 
{
  "rootfi_id": 8002,
  "platform_id": "ref_shopify_001",
  "type": "refund",
  "order_id": "ord_123456",
  "original_transaction_id": "8001",
  "currency_id": "USD",
  "amount": 50.00,
  "status": "completed",
  "payment_method_type": "card",
  "gateway": "shopify_payments",
  "reason": "customer_request",
  "description": "Partial refund - contact return"
}

​
Properties Supported (Legacy)

PropertyTypeDescription
platform_idstringThe Platform’s ID for the refund
parent_data_modelstringThe parent data model type
parent_data_model_idstringThe ID of the parent order
currency_idstringCurrency code
sub_totalnumberSubtotal of refund
total_amountnumberTotal refund amount
created_atstringCreated timestamp
updated_atstringUpdated timestamp
{
  "rootfi_id": 157,
  "rootfi_created_at": "2024-01-22T05:07:31.465Z",
  "rootfi_updated_at": "2024-01-22T05:07:31.000Z",
  "rootfi_company_id": 1089,
  "platform_id": "ref_123456",
  "parent_data_model": "ECOMMERCE_ORDERS",
  "parent_data_model_id": "ord_123456",
  "currency_id": "USD",
  "sub_total": 89.99,
  "total_amount": 97.19,
  "created_at": "2024-01-22T05:07:31.465Z",
  "updated_at": "2024-01-22T05:07:31.465Z"
}