# Scheduled Transfers

Scheduled transfers give channels granular control over when merchant payouts are executed. Instead of transferring funds immediately after payment capture, you can configure Violet to hold distributions until specific conditions are met—such as order fulfillment—and batch multiple transfers together on a schedule.

{% hint style="info" %}
**Destination Payments Requirement**: If your app uses the [Destination Payments](https://docs.violet.io/prism/payments/transfer-mechanisms#destination-payments) transfer mechanism, scheduled transfers are **required**. This ensures proper coordination between atomic payment capture and fund distribution timing.
{% endhint %}

## Why Use Scheduled Transfers?

### The Problem with Immediate Transfers

In a traditional `AUTOMATIC` transfer setup, funds are transferred to merchants immediately after payment capture. While this provides fast payouts, it creates challenges for certain business models:

* **Fulfillment Risk**: Merchants receive payment before shipping, increasing exposure if orders are cancelled or not fulfilled
* **High Transaction Volume**: Each order generates a separate transfer, leading to numerous small transactions
* **Chargeback Exposure**: Funds are already with the merchant when disputes arise
* **Operational Complexity**: Difficult to reconcile when transfers happen at unpredictable times

### How Scheduled Transfers Help

Scheduled transfers address these challenges by introducing two powerful configuration options:

1. **Fulfillment Requirements**: Only transfer funds for orders that have been shipped or delivered
2. **Batched Transfers**: Aggregate multiple orders into a single transfer on a schedule

## Configuration Options

Scheduled transfer settings are part of your app's payment configuration. Contact your Violet representative to enable these features.

Scheduled transfer settings can be configured at two levels:

* **App Level**: Settings apply to all merchants connected to your app by default
* **Merchant Level**: Override app-level settings for specific merchants who require different transfer schedules

This flexibility allows you to set sensible defaults at the app level while accommodating merchants with unique business requirements or risk profiles.

{% hint style="info" %}
**Ready to configure scheduled transfers?** Transfer schedule settings are managed by the Violet team. To learn more about scheduled transfers or configure a transfer schedule for your app or specific merchants, please [reach out to Violet](mailto:support@violet.io).
{% endhint %}

### Transfer Schedule Settings

#### `require_fulfillment`

Controls whether bag fulfillment status is required before transfers are executed.

| Value             | Behavior                                                                              |
| ----------------- | ------------------------------------------------------------------------------------- |
| `false` (default) | Transfers execute immediately after payment capture, regardless of fulfillment status |
| `true`            | Transfers only execute for bags in `SHIPPED` or `DELIVERED` status                    |

**When to use `require_fulfillment: true`:**

* You want to ensure merchants are paid only after orders ship
* Your business model involves dropshipping or print-on-demand where fulfillment timing varies
* You want to reduce financial risk from unfulfilled orders
* Merchants have historically had fulfillment issues

#### `time_interval_seconds`

Sets the time interval in seconds after which a distribution is eligible to be transferred.

| Value         | Behavior                                                  |
| ------------- | --------------------------------------------------------- |
| `0` (default) | Transfers execute immediately (no batching)               |
| `86400`       | Distribution eligible for transfer after 1 day (24 hours) |
| `604800`      | Distribution eligible for transfer after 7 days (7 days)  |
| Custom value  | Any interval in seconds                                   |

**When to use batched transfers:**

* You want to reduce the number of individual transfer transactions
* You want to ensure distributions are held for a certain amount of time before being paid out
* Merchants prefer receiving consolidated payouts
* You're processing high volumes of small orders

## How It Works

### Architecture Overview

When scheduled transfers are enabled, Violet uses a **queued distribution** system:

```
Order Placed → Payment Captured → Distribution Created → Queued for Transfer
                                                              ↓
                                          Nightly Job Checks Eligibility
                                                              ↓
                                    Eligible? → Create Transfer → Merchant Paid
                                    Not Eligible? → Remains Queued
```

### Eligibility Criteria

A queued distribution becomes eligible for transfer when ALL of the following are true:

1. **Fulfillment Check** (if `require_fulfillment: true`):
   * Bag status is `SHIPPED` or `DELIVERED`
2. **Time Interval Check** (if `time_interval_seconds > 0`):
   * This amount of time has passed since the distribution was created
3. **Standard Checks**:
   * Merchant has a valid, active payout account
   * No holds or restrictions on the merchant account

### Processing Schedule

Queued distributions are processed by a nightly job that runs at **11:00 PM UTC** daily. The job:

1. Finds all eligible queued distributions
2. Groups distributions by merchant
3. Creates a single transfer per merchant (batching all eligible distributions)
4. Updates distribution and transfer statuses
5. Sends `TRANSFER_SENT` webhook events

{% hint style="info" %}
**Timing Note**: The 11:00 PM UTC processing time means merchants in different time zones will see payouts arrive at different local times. For US-based merchants, this typically means early evening payouts.
{% endhint %}

## Net Amount Calculation

When processing scheduled transfers, Violet calculates a **net transfer amount** for each merchant by combining all pending distributions—including payments, refunds, and adjustments.

### How It Works

Instead of processing each distribution as a separate transfer, Violet aggregates them:

```
Net Transfer = Payment Distributions + Refund Distributions + Adjustment Distributions
               (positive)              (negative)             (positive or negative)
```

This means:

* **Payments** add to the merchant's payout (positive)
* **Refunds** reduce the merchant's payout (negative)
* **Adjustments** can increase or decrease the payout

### Example: Payment with Refund

**Scenario**: A merchant has a $100 order with a partial refund issued before the scheduled transfer runs.

| Distribution Type | Amount  | Status  |
| ----------------- | ------- | ------- |
| Payment           | +$90.00 | PENDING |
| Refund            | -$22.50 | PENDING |

**Net Transfer**: $90.00 - $22.50 = **$67.50**

The merchant receives a single transfer of $67.50, not two separate transactions.

### Example: Payment with Refund and Adjustment

**Scenario**: A merchant has a $100 order, a partial refund, and a shipping correction adjustment.

| Distribution Type | Amount  | Status  | Notes                    |
| ----------------- | ------- | ------- | ------------------------ |
| Payment           | +$90.00 | PENDING | Original order           |
| Refund            | -$22.50 | PENDING | Partial return           |
| Adjustment        | +$5.00  | PENDING | Shipping rate correction |

**Net Transfer**: $90.00 - $22.50 + $5.00 = **$72.50**

### Edge Cases

#### Zero Net Amount

If refunds exactly equal the payment amount:

| Distribution Type | Amount    |
| ----------------- | --------- |
| Payment           | +$50.00   |
| Refund            | -$50.00   |
| **Net**           | **$0.00** |

**Result**: No transfer is executed. The distributions remain pending and will be included in the next scheduled transfer cycle when the merchant has additional positive distributions.

#### Negative Net Amount

If refunds or adjustments exceed the payment amount:

| Distribution Type | Amount      |
| ----------------- | ----------- |
| Payment           | +$50.00     |
| Refund #1         | -$30.00     |
| Refund #2         | -$30.00     |
| **Net**           | **-$10.00** |

**Result**: The transfer is skipped for this settlement cycle. The negative balance carries forward and will be deducted from the merchant's next payout when they have sufficient positive distributions.

{% hint style="warning" %}
**Important**: Merchants cannot have negative balances indefinitely. If a merchant consistently has negative net amounts, review their refund patterns and consider appropriate action.
{% endhint %}

## Refunds and Adjustments

Understanding how refunds and adjustments interact with scheduled transfers is critical for accurate payout expectations.

### Refunds Before Settlement

When a refund is issued **before** the scheduled transfer runs:

1. A negative `REFUND` distribution is created
2. It's included in the net calculation for the next scheduled transfer
3. The merchant receives the net amount (payment minus refund)

**Timeline**:

```
Day 1: Order placed, +$90.00 distribution created (PENDING)
Day 2: Order ships, fulfillment requirement met
Day 3: Customer requests refund, -$22.50 distribution created (PENDING)
Day 4: Scheduled transfer runs
       → Net: $90.00 - $22.50 = $67.50 transferred
```

### Refunds After Settlement

When a refund is issued **after** the distribution has already been transferred:

1. A new negative `REFUND` distribution is created
2. This distribution is marked as `PENDING`
3. It will be deducted from the merchant's **next** scheduled transfer

**Timeline**:

```
Day 1: Order placed, +$90.00 distribution created (PENDING)
Day 2: Order ships
Day 3: Scheduled transfer runs, $90.00 transferred to merchant ✓
Day 5: Customer requests refund, -$22.50 distribution created (PENDING)
Day 8: New order placed, +$90.00 distribution created (PENDING)
Day 9: New order ships
Day 10: Scheduled transfer runs
        → Net: $90.00 (new order) - $22.50 (refund from Day 5) = $67.50 transferred
```

### Adjustments

Adjustments are corrections made to distributions after the fact, such as:

* Shipping rate corrections
* Commission adjustments
* Platform error compensation

Adjustments create their own distributions that follow the same rules:

* **Positive adjustments** increase the merchant's payout
* **Negative adjustments** decrease the merchant's payout

Like refunds, adjustments are included in the net calculation for the next scheduled transfer.

## Use Cases

### Use Case 1: Dropshipping Marketplace

**Scenario**: A marketplace connects shoppers with dropship merchants who fulfill orders from third-party suppliers. Fulfillment times vary from 2-14 days.

**Challenge**: With immediate transfers, merchants receive payment before confirming they can fulfill the order. If a supplier is out of stock, the merchant has already been paid.

**Solution**:

```json
{
  "transfer_schedule": {
    "require_fulfillment": true,
    "time_interval_seconds": 0
  }
}
```

**Result**: Merchants receive payment only after marking orders as shipped, ensuring they've confirmed fulfillment capability before receiving funds.

***

### Use Case 2: High-Volume, Low-Value Orders

**Scenario**: A social commerce platform processes thousands of small orders daily, averaging $15-25 per order.

**Challenge**: Each order generates a separate transfer, creating thousands of micro-transactions. This increases payment processing overhead and makes reconciliation difficult.

**Solution**:

```json
{
  "transfer_schedule": {
    "require_fulfillment": false,
    "time_interval_seconds": 86400
  }
}
```

**Result**: Merchants receive a single daily transfer aggregating all their orders from the past 24 hours, reducing transaction volume by 90%+ and simplifying reconciliation.

***

### Use Case 3: Risk-Conscious Marketplace

**Scenario**: A marketplace has experienced chargebacks and disputes when merchants fail to fulfill orders or ship counterfeit goods.

**Challenge**: By the time a dispute is raised, funds have already been transferred to the merchant, making recovery difficult.

**Solution**:

```json
{
  "transfer_schedule": {
    "require_fulfillment": true,
    "time_interval_seconds": 604800
  }
}
```

**Result**:

* Funds are held until orders are confirmed shipped
* Weekly batching provides a 7-day buffer for issues to surface
* More time to identify and address problems before merchant payout

***

### Use Case 4: Predictable Payout Schedules

**Scenario**: A B2B marketplace wants to offer merchants predictable "payday" schedules rather than sporadic transfers.

**Challenge**: Merchants prefer knowing exactly when to expect payments for cash flow planning.

**Solution**:

```json
{
  "transfer_schedule": {
    "require_fulfillment": false,
    "time_interval_seconds": 604800
  }
}
```

**Result**: Merchants receive weekly payouts on a predictable schedule, improving their ability to manage cash flow and plan expenses.

## Combining with Transfer Methods

Scheduled transfers work with different [transfer methods](https://docs.violet.io/prism/payments/payment-settings/transfer-settings):

| Transfer Method | Scheduled Transfers Behavior                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------- |
| `AUTOMATIC`     | Distributions are queued and processed by the nightly job based on your schedule settings       |
| `CUSTOM`        | Distributions are queued; you can trigger transfers via API or let the nightly job process them |
| `EXTERNAL`      | Not applicable—transfers handled outside Violet                                                 |
| `DISABLED`      | Not applicable—no distributions created                                                         |

## Monitoring Queued Distributions

### Dashboard Visibility

Merchants can view their pending (queued) distributions in the Merchant Dashboard. The distributions will show:

* Status: `PENDING` (waiting for transfer)
* Associated order and bag information
* Expected payout timing based on your configuration

### API Access

Use the [Search Distributions API](https://docs.violet.io/api-reference/payments/distributions/search-distributions) to query queued distributions:

```bash
GET /distributions?status=PENDING&merchant_id={merchant_id}
```

### Webhook Events

When scheduled transfers are processed, you'll receive standard transfer webhook events:

* `TRANSFER_SENT`: Transfer successfully created and sent to merchant
* `TRANSFER_FAILED`: Transfer failed (includes error details)

## Best Practices

### Setting Appropriate Intervals

| Business Type             | Recommended `time_interval_seconds`  |
| ------------------------- | ------------------------------------ |
| High-volume, small orders | `86400` (daily)                      |
| Standard e-commerce       | `0` or `86400`                       |
| B2B with large orders     | `604800` (weekly)                    |
| Dropship/POD              | `0` with `require_fulfillment: true` |

### Communicating with Merchants

When enabling scheduled transfers, communicate clearly with merchants about:

* When they can expect to receive payouts
* How fulfillment status affects their payouts (if applicable)
* Where to view pending distributions in the dashboard

### Handling Edge Cases

**Partial Fulfillment**: If a bag is partially fulfilled, transfers are only created for the fulfilled portion when `require_fulfillment` is enabled.

**Refunds**: Refund distributions are included in the net amount calculation for scheduled transfers. See [Refunds and Adjustments](#refunds-and-adjustments) for details.

**Manual Overrides**: You can still trigger transfers manually via the API for urgent situations, bypassing the scheduled processing.

## FAQ

**Q: What happens to distributions if a merchant doesn't fulfill an order?**

A: With `require_fulfillment: true`, distributions remain in `PENDING` status indefinitely until the bag is marked as `SHIPPED` or `DELIVERED`. Consider implementing processes to handle long-unfulfilled orders.

**Q: Can I have different schedules for different merchants?**

A: Yes! Transfer schedule settings can be configured at both the app level (applying to all merchants by default) and at the merchant level (overriding app defaults for specific merchants). This allows you to set standard defaults while customizing schedules for merchants with unique requirements. [Reach out to Violet](mailto:support@violet.io) to configure merchant-specific transfer schedules.

**Q: What time zone does the nightly job use?**

A: The processing job runs at 11:00 PM UTC daily. Plan your merchant communications accordingly based on their local time zones.

**Q: Can I trigger a transfer manually before the scheduled time?**

A: Yes, you can use the [Transfer Funds API](https://docs.violet.io/api-reference/orders-and-checkout/transfers/transfer-funds-single-order) to manually trigger transfers for specific orders or bags at any time.

**Q: How do I enable scheduled transfers for my app?**

A: Transfer schedule settings are managed by the Violet team. [Reach out to Violet](mailto:support@violet.io) to discuss your requirements and configure scheduled transfer settings for your app or specific merchants.

**Q: Why did a merchant receive less than the order amount?**

A: The payout amount is calculated as a **net** of all pending distributions. Common reasons for reduced payouts include:

* Refunds issued before settlement (negative distributions deducted)
* Adjustments applied (can be positive or negative)
* Multiple orders combined with refunds from previous orders

Check the merchant's distribution history to see all contributing amounts.

**Q: What happens to a refund issued after the merchant was already paid?**

A: The refund creates a new negative distribution marked as `PENDING`. This amount will be deducted from the merchant's next scheduled transfer. If the merchant has no upcoming orders, the negative balance carries forward until they have sufficient positive distributions.

**Q: Can a merchant's payout be zero or negative?**

A: Yes. If refunds equal the payment amount, no transfer is executed (net = $0). If refunds exceed payments, the transfer is skipped and the negative balance carries forward. The negative amount will be deducted from the merchant's next payout when they have sufficient positive distributions.

**Q: How do adjustments affect scheduled transfers?**

A: Adjustments (such as shipping corrections or commission fixes) create their own distributions that are included in the net calculation. Positive adjustments increase the payout; negative adjustments decrease it. Like refunds, adjustments are processed in the next scheduled transfer cycle.