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, CREDIT_NOTE, FEE, CHARGEBACK, PAYOUT, ADJUSTMENT
  • Payment Method Details: CARD, BANK_TRANSFER, WIRE_TRANSFER, PAYPAL, APPLE_PAY, GOOGLE_PAY, CHECK, CASH, CRYPTO, OTHER, UNKNOWN
  • 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.)

​
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": "REFUNDED",
  "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"
}