# Order Transfer Groups

### Overview

The Order Transfer Group APIs provide an **order-centric view** of transfer activity, complementing Violet's core [Transfer APIs](https://docs.violet.io/api-reference/payments/transfers). 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](https://docs.violet.io/prism/payments/payments-during-checkout/transfers).

### 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**:

```json
// 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](https://docs.violet.io/api-reference/payments/transfers). For transfer reversal scenarios, see [Transfer Reversals](https://docs.violet.io/prism/payments/payments-during-checkout/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**](https://app.gitbook.com/o/4fIo3y35EjIdKNlJq07P/s/8lXIp71Ct5qCUhXjko2q/api-reference/order-service/transfers/get-order-transfer-group)**.**

#### 2. Get Bag Transfer Group

Retrieves transfer information for a specific bag within an order.

**Learn more in our** [**API Reference**](https://app.gitbook.com/o/4fIo3y35EjIdKNlJq07P/s/8lXIp71Ct5qCUhXjko2q/api-reference/order-service/transfers/get-bag-transfer-group)**.**

#### 3. Get Multiple Order Transfer Groups

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

**Learn more in our** [**API Reference**](https://app.gitbook.com/o/4fIo3y35EjIdKNlJq07P/s/8lXIp71Ct5qCUhXjko2q/api-reference/order-service/transfers/get-order-transfer-groups)**.**

#### 4. Get Multiple Bag Transfer Groups

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

**Learn more in our** [**API Reference**](https://app.gitbook.com/o/4fIo3y35EjIdKNlJq07P/s/8lXIp71Ct5qCUhXjko2q/api-reference/order-service/transfers/get-bag-transfer-groups)**.**

### 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**](https://docs.violet.io/api-reference/payments/transfers) **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](https://docs.violet.io/prism/webhooks).

#### 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](https://docs.violet.io/api-reference/payments/transfers).

```javascript
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**](https://docs.violet.io/api-reference/payments/transfers) **and** [**Transfer search functionality**](https://docs.violet.io/api-reference/payments/transfers)**.**

### 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:

* **Order Transfer Group issues**: Contact support with specific order IDs
* **Individual transfer problems**: Use [Transfer APIs](https://docs.violet.io/api-reference/payments/transfers) to get detailed transfer information
* **Transfer reversal issues**: See [Transfer Reversals documentation](https://docs.violet.io/prism/payments/payments-during-checkout/transfer-reversals)

### Related Documentation

* [**Transfer Overview**](https://docs.violet.io/prism/payments/payments-during-checkout/transfers) - Foundational transfer concepts and lifecycle
* [**Transfer APIs**](https://docs.violet.io/api-reference/payments/transfers) - Individual transfer operations and management
* [**Transfer Reversals**](https://docs.violet.io/prism/payments/payments-during-checkout/transfer-reversals) - Understanding and handling transfer reversals
* [**Handling Failed Transfers**](https://docs.violet.io/prism/payments/payments-during-checkout/guides/handling-failed-transfers) - Understanding and handling transfer reversals


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/prism/payments/payments-during-checkout/order-transfer-groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.