Order Transfer Groups

Overview

The Order Transfer Group APIs provide an order-centric view of transfer activity, complementing Violet's core Transfer APIs. While the Transfer APIs focus on individual transfer operations and lifecycle management, the Order Transfer Group APIs organize transfer data by business context—specifically around Orders and Bags.

When to use Order Transfer Group APIs:

  • Tracking payout completion status for multi-merchant orders

  • Debugging transfer issues at the order or bag level

  • Understanding the relationship between orders and their associated transfers

When to use Transfer APIs instead:

  • Managing individual transfer operations

  • Creating or registering transfers

  • Detailed transfer lifecycle management

  • Working with transfer reversals

For foundational knowledge about transfers, including how they work and their lifecycle, see our Transfer Overview.

Key Concepts

Order Transfer Group

An OrderTransferGroup represents the complete set of money movement attempts associated with a single order, organized by merchant and bag. It includes a computed summary indicating whether all expected transfers have been successfully sent.

Bag Transfer Group

A BagTransferGroup focuses on transfer attempts for a single bag and merchant combination within an order. This provides granular tracking for debugging merchant transfer issues at the bag level.

Relationship Between OrderTransfer and Transfer

Understanding the relationship between OrderTransfer records and Transfer objects is crucial for interpreting the API responses:

One-to-Many Relationship: A single Transfer object may be associated with multiple OrderTransfer records across different orders or bags. This occurs in several scenarios:

  • Batch Transfers: When funds from multiple orders are combined into a single payout to a merchant, one Transfer will appear across multiple OrderTransferGroup or BagTransferGroup responses

Important Implications:

  • transfer.id is not a unique identifier per order_id or bag_id

  • The same transfer.id may appear in responses for different orders when those orders were part of a batch transfer

  • When analyzing transfer data, always consider the related_orders and related_bags arrays in the transfer object to understand the full scope of what a single transfer covers

Example Scenario:

// Transfer ID 349890 appears in multiple orders due to batch processing
// Order 12345 response
{
  "order_id": 12345,
  "group": [{
    "transfers": [{
      "id": 349890,
      "related_orders": ["12345", "12346", "12347"],
      "related_bags": ["8220083", "8220084", "8220085"]
    }]
  }]
}

// Order 12346 response (same Transfer ID)
{
  "order_id": 12346, 
  "group": [{
    "transfers": [{
      "id": 349890,  // Same transfer ID as above
      "related_orders": ["12345", "12346", "12347"],
      "related_bags": ["8220083", "8220084", "8220085"]
    }]
  }]
}

This relationship ensures complete traceability while supporting efficient batch processing of payments to merchants.

Completion Logic

The is_complete field represents whether all expected transfers for an order or bag have been successfully sent. This is calculated by checking that all related transfers have a status of SENT.

Transfer Status Interpretation:

  • is_complete: true - All transfers are in SENT status

  • is_complete: false - One or more transfers are in FAILED, REVERSED, or PARTIALLY_REVERSED status

Note: For detailed information about transfer statuses and their meanings, see the Transfer API documentation. For transfer reversal scenarios, see Transfer Reversals.

API Endpoints

1. Get Order Transfer Group

Retrieves all transfer information for a specific order, grouped by bag and merchant.

Learn more in our API Reference.

2. Get Bag Transfer Group

Retrieves transfer information for a specific bag within an order.

Learn more in our API Reference.

3. Get Multiple Order Transfer Groups

Retrieves transfer groups for multiple orders with optional filtering by completion status.

Learn more in our API Reference.

4. Get Multiple Bag Transfer Groups

Retrieves transfer groups for multiple bags with optional filtering by completion status.

Learn more in our API Reference.

Order Transfer Group Specific Behavior

Multi-Attempt Visibility

Unlike individual Transfer API responses, Order Transfer Group APIs show all transfer attempts for an order or bag, including failed ones. This order-centric view provides:

  • Complete audit trail per order

  • Retry attempt history

  • Debugging context for incomplete transfers

Transfer Ordering in Groups

Transfers within each group are ordered by priority of finality:

  1. Successful transfers (SENT) appear first

  2. Failed attempts appear after, ordered by recency

This allows quick identification of successful transfers while preserving failure history for debugging.

Cross-Order Transfer Relationships

A key difference from individual Transfer APIs is how Order Transfer Groups handle batch transfers:

  • The same transfer.id appears across multiple Order Transfer Group responses when orders were batched

  • Each order gets its own Order Transfer Group response, but they reference the shared transfer

  • Use related_orders and related_bags arrays to understand the full scope of batch operations

For individual transfer details and lifecycle management, use the Transfer APIs directly.

Best Practices

1. Listen for Webhooks

When monitoring transfer completion, integrate with our payments webhooks to receive real-time updates on transfer status changes. This allows you to react immediately to transfer completions or failures without polling the API.

Learn more about webhooks in our Webhooks documentation.

2. Order-Level Error Analysis

When analyzing failed transfers at the order level, examine both the status field and errors array. For detailed transfer error handling, see Transfer API documentation.

function analyzeOrderTransferFailures(transferGroup) {
  const failures = [];
  
  transferGroup.group.forEach(bagGroup => {
    bagGroup.transfers.forEach(transfer => {
      if (transfer.status === 'FAILED') {
        failures.push({
          transferId: transfer.id,
          bagId: bagGroup.bag_id,
          merchantId: bagGroup.merchant_id,
          errors: transfer.errors,
          amount: transfer.amount,
          // Use Transfer APIs for detailed error investigation
          transferApiUrl: `/transfers/${transfer.id}`
        });
      }
    });
  });
  
  return failures;
}

3. Order-Centric Monitoring

The Order Transfer Group APIs are ideal for business-level monitoring:

  • Order completion tracking - Monitor is_complete status across orders

  • Merchant-specific issues - Group failures by merchant_id across bags

  • Multi-merchant order problems - Identify orders with mixed success/failure across merchants

  • Batch transfer anomalies - Detect when related orders have inconsistent transfer outcomes

For transfer-level monitoring and detailed analytics, use the Transfer APIs and Transfer search functionality.

Support and Troubleshooting

Common Issues

  1. Incomplete transfers - Check individual transfer status and error messages

  2. Missing transfers - Verify that transfer processing was initiated for the order/bag

  3. Status inconsistencies - Ensure you're checking the most recent transfer attempt

Getting Help

For additional support:

Related Documentation

PreviousTransfer ReversalsNextFee Structure

Last updated

Was this helpful?