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.

Destination Payments Requirement: If your app uses the Destination Payments transfer mechanism, scheduled transfers are required. This ensures proper coordination between atomic payment capture and fund distribution timing.

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.

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.

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

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.

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.

Important: Merchants cannot have negative balances indefinitely. If a merchant consistently has negative net amounts, review their refund patterns and consider appropriate action.

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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 to query queued distributions:

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 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 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 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 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.